Architecture Overview

nself-chat System Architecture - High-level design and technical overview.

Version: 1.0.0 | Last Updated: April 17, 2026

---

🎯 Executive Summary

nself-chat is a production-ready, white-label team communication platform built as a monorepo with separate backend and frontend concerns. It supports 6 platforms (Web, iOS, Android, Windows, macOS, Linux) from a single React codebase.

Key Design Principles:

• Separation of Concerns: Backend (nself CLI) and Frontend (React) are independent
• Code Reuse: Shared packages across all platform apps
• Type Safety: 100% TypeScript with zero errors
• Production Ready: Zero compromises on quality, security, or performance

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        nself-chat v1.0.0                        │
│                    Multi-Platform Chat System                   │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
┌───────▼────────┐                         ┌────────▼────────┐
│    Frontend    │                         │     Backend     │
│   (React 19)   │◄────────────────────────┤  (nself CLI)    │
│                │     GraphQL/WebSocket   │                 │
└────────────────┘                         └─────────────────┘
        │                                           │
        │                                           │
┌───────▼────────────────────────────┐    ┌────────▼─────────────────┐
│     Platform Apps                  │    │   Backend Services       │
├────────────────────────────────────┤    ├──────────────────────────┤
│ • Web (Next.js 15)                 │    │ • PostgreSQL (database)  │
│ • iOS (Capacitor 6)                │    │ • Hasura (GraphQL)       │
│ • Android (Capacitor 6)            │    │ • Auth (Nhost)           │
│ • Windows (Electron 33)            │    │ • MinIO (storage)        │
│ • macOS (Electron 33)              │    │ • Redis (cache)          │
│ • Linux (Electron 33)              │    │ • MeiliSearch (search)   │
└────────────────────────────────────┘    │ • Mailpit (email dev)    │
                                          │ • Nginx (proxy)          │
                                          └──────────────────────────┘

---

📁 Monorepo Structure

Project Layout

nself-chat/
├── backend/                  # Backend infrastructure (nself CLI)
│   ├── migrations/          # SQL migrations (222 tables)
│   ├── hasura/             # GraphQL metadata and permissions
│   ├── nginx/              # Reverse proxy configuration
│   ├── postgres/           # PostgreSQL init scripts
│   ├── auth/               # Auth service configuration
│   ├── schema.dbml         # Database schema (DBML format)
│   ├── docker-compose.yml  # Generated by nself build
│   ├── .env                # Local environment config
│   └── README.md           # Backend documentation
│
├── frontend/                # Frontend monorepo (all platforms)
│   ├── apps/
│   │   ├── web/            # Next.js 15 web application
│   │   │   ├── src/        # Source code
│   │   │   │   ├── app/    # Next.js App Router
│   │   │   │   ├── components/
│   │   │   │   ├── hooks/
│   │   │   │   ├── lib/
│   │   │   │   └── services/
│   │   │   ├── public/     # Static assets
│   │   │   ├── package.json
│   │   │   └── README.md
│   │   │
│   │   ├── mobile/         # Capacitor mobile app
│   │   │   ├── src/        # React source code
│   │   │   ├── android/    # Native Android project
│   │   │   ├── ios/        # Native iOS project
│   │   │   ├── capacitor.config.json
│   │   │   └── README.md
│   │   │
│   │   └── desktop/        # Electron desktop app
│   │       ├── src/
│   │       │   ├── main/   # Main process (Node.js)
│   │       │   ├── preload/# Preload scripts
│   │       │   ├── renderer/# Renderer process (React)
│   │       │   └── adapters/# Platform adapters
│   │       ├── build/      # Build resources (icons)
│   │       ├── electron-builder.json
│   │       └── README.md
│   │
│   ├── packages/           # Shared packages (code reuse)
│   │   ├── ui/            # Radix UI components
│   │   ├── config/        # Configuration types
│   │   ├── lib/           # Utility functions
│   │   ├── graphql/       # GraphQL client & queries
│   │   ├── auth/          # Authentication logic
│   │   ├── state/         # State management (Zustand)
│   │   └── types/         # TypeScript types
│   │
│   ├── tooling/           # Development tooling
│   │   └── eslint/        # Shared ESLint config
│   │
│   ├── package.json       # Root workspace config
│   ├── pnpm-workspace.yaml
│   └── README.md
│
├── .wiki/                 # Complete documentation (228 files)
│   ├── Home.md           # Documentation home
│   ├── getting-started/
│   ├── features/
│   ├── guides/
│   ├── api/
│   ├── deployment/
│   └── ...
│
├── .github/              # GitHub Actions CI/CD
│   └── workflows/        # 19 workflow files
│
├── .claude/              # Claude Code context (gitignored)
│   └── v092/            # Current version tracking
│
├── scripts/              # Build and utility scripts
├── package.json          # Root package.json
├── README.md            # Project overview
└── LICENSE              # MIT License

---

🔧 Backend Architecture

nself CLI Stack

The backend uses nself CLI v1.0.6 for a complete BaaS (Backend as a Service) stack.

Core Services (required):

1. PostgreSQL 16 - Primary database with 60+ extensions
2. Hasura 2.x - GraphQL Engine with permissions
3. Auth - Nhost Authentication service
4. Nginx - Reverse proxy + SSL termination

Optional Services (configurable via .env):

• nself-admin - Admin UI (port 3021)
• MinIO - S3-compatible object storage
• Redis - Cache and session storage
• MeiliSearch - Full-text search engine
• Mailpit - Email testing (dev only)
• Monitoring Stack - Grafana, Prometheus, Loki, etc.

Database Schema

222 tables organized by feature:

• Core Tables: users, profiles, channels, messages, threads
• RBAC: roles, permissions, user_roles
• Features: reactions, bookmarks, pins, attachments
• Advanced: guilds, categories, broadcasts, bots
• Multi-Tenancy: workspaces, subscriptions, billing
• Analytics: events, metrics, audit_logs

Schema Format: DBML (Database Markup Language) in backend/schema.dbml

GraphQL API

Hasura provides:

• Auto-generated GraphQL API from PostgreSQL schema
• Real-time subscriptions via WebSocket
• Role-based permissions (RBAC)
• Remote schemas for custom business logic
• Actions for REST API integration

API Endpoints:

• GraphQL: /v1/graphql
• WebSocket: /v1/graphql (ws://)
• Admin Console: /console

---

💻 Frontend Architecture

Multi-Platform Strategy

One codebase → Six platforms using React 19:

Platform	Technology	Build Output
Web	Next.js 15 (SSR/SSG)	Static HTML + JS
iOS	Capacitor 6 + WebView	.ipa (App Store)
Android	Capacitor 6 + WebView	.apk/.aab (Play Store)
Windows	Electron 33	.exe installer
macOS	Electron 33	.dmg disk image
Linux	Electron 33	.AppImage/.deb/.rpm

Shared Packages

Monorepo design maximizes code reuse:

// Example: Importing from shared packages
import { Button } from '@nself-chat/ui'
import { useAuth } from '@nself-chat/auth'
import { apolloClient } from '@nself-chat/graphql'
import { logger } from '@nself-chat/lib'

Benefits:

• ✅ Single source of truth for types
• ✅ Consistent UI across all platforms
• ✅ Shared business logic
• ✅ Easier testing and maintenance

Platform Adapters

Each platform has adapters for native features:

Mobile Adapters (frontend/apps/mobile/src/adapters/):

• storage/ - AsyncStorage → LocalStorage interface
• auth/ - Biometric authentication (Face ID, Touch ID)
• notifications/ - Push notifications (FCM/APNS)
• camera/ - Photo capture and gallery access
• network/ - Connectivity monitoring

Desktop Adapters (frontend/apps/desktop/src/adapters/):

• storage/ - electron-store → LocalStorage interface
• notifications/ - Native desktop notifications
• clipboard/ - System clipboard access
• filesystem/ - File system operations
• window/ - Window management

State Management

Zustand 5.0 for local state:

// Example: Auth store
import { create } from 'zustand'

const useAuthStore = create((set) => ({
  user: null,
  login: (user) => set({ user }),
  logout: () => set({ user: null }),
}))

Apollo Client 3.12 for server state:

// Example: GraphQL query
const { data, loading } = useQuery(GET_MESSAGES, {
  variables: { channelId },
})

UI Component Library

Radix UI primitives + Tailwind CSS styling:

• Accessible (WCAG 2.1 AA compliant)
• Unstyled primitives (full control)
• Dark/light mode support
• Consistent across all platforms

---

🔐 Security Architecture

Authentication Flow

┌──────────┐      ┌──────────┐      ┌──────────┐
│  Client  │─────▶│   Auth   │─────▶│ Hasura   │
│ (Browser)│      │ Service  │      │ GraphQL  │
└──────────┘      └──────────┘      └──────────┘
     │                  │                  │
     │                  │                  │
     ▼                  ▼                  ▼
  JWT Token      JWT Secret         JWT Validation
  (httpOnly      (HMAC-SHA256)      (x-hasura-* claims)
   cookie)

Auth Methods:

• Email + Password
• Magic Links (passwordless)
• 11 OAuth Providers (Google, GitHub, Apple, etc.)
• 2FA/TOTP (optional)
• Biometric (mobile)

Authorization (RBAC)

5 built-in roles with granular permissions:

1. Owner - Full access to everything
2. Admin - User and channel management
3. Moderator - Content moderation
4. Member - Standard user
5. Guest - Limited read-only access

Permission Examples:

// Hasura permission rules (simplified)
{
  "select": {
    "filter": {
      "_or": [
        { "channel.type": "public" },
        { "channel.members.user_id": "X-Hasura-User-Id" }
      ]
    }
  }
}

Data Security

• End-to-End Encryption: Signal Protocol (Double Ratchet)
• Transport Security: HTTPS/TLS 1.3
• Database Encryption: At-rest encryption (optional)
• Secrets Management: Environment variables + vault
• Input Sanitization: DOMPurify for XSS prevention
• CSRF Protection: SameSite cookies
• Rate Limiting: Redis-based rate limiting

---

🚀 Deployment Architecture

Development Environment

Developer Machine
├── Backend (Docker)
│   └── 8 services running via nself CLI
└── Frontend (Node.js)
    └── pnpm dev (port 3000)

Production Architecture (Recommended)

┌─────────────────────────────────────────────┐
│              Load Balancer                  │
│         (nginx, Cloudflare, etc.)           │
└─────────────┬───────────────────────────────┘
              │
    ┌─────────┴─────────┐
    │                   │
┌───▼────┐         ┌────▼────┐
│  Web   │         │ Backend │
│ Nodes  │         │ Cluster │
│ (Next) │         │(Hasura) │
└────────┘         └─────────┘
    │                   │
    │              ┌────▼────┐
    │              │   DB    │
    └──────────────▶(Postgres)
                   └─────────┘

Deployment Options

Option	Best For	Complexity
Vercel	Web app only	Low
Docker	Self-hosted	Medium
Kubernetes	Enterprise scale	High
AWS/GCP/Azure	Full control	High

---

📊 Data Flow

Real-Time Messaging

User A                    Server                    User B
  │                         │                         │
  │─────(1) Send Msg───────▶│                         │
  │      (GraphQL)          │                         │
  │                         │                         │
  │◀────(2) Confirm ────────│                         │
  │      (200 OK)           │                         │
  │                         │                         │
  │                         │──(3) Push Msg──────────▶│
  │                         │   (WebSocket)           │
  │                         │                         │
  │                         │◀────(4) Ack─────────────│
  │                         │                         │

Steps:

1. User A sends message via GraphQL mutation
2. Server validates, saves to DB, returns confirmation
3. Server pushes message to User B via WebSocket subscription
4. User B acknowledges receipt

File Upload Flow

Client                 Frontend              MinIO            Database
  │                       │                    │                 │
  │─(1) Select File──────▶│                    │                 │
  │                       │                    │                 │
  │                       │─(2) Get Upload URL─▶│                │
  │                       │                    │                 │
  │                       │◀─(3) Signed URL────│                 │
  │                       │                    │                 │
  │◀─(4) Upload Direct────┼────────────────────▶│                │
  │                       │                    │                 │
  │                       │─(5) Save Metadata──┼────────────────▶│
  │                       │                    │                 │
  │◀─(6) Success──────────│                    │                 │

Benefits:

• Direct upload to S3 (faster)
• No frontend server load
• Scalable file storage

---

🔄 Development Workflow

Git Branch Strategy

main (production)
  │
  └── develop (staging)
        │
        ├── feature/new-feature
        ├── fix/bug-fix
        └── refactor/code-cleanup

CI/CD Pipeline

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Commit    │────▶│  CI Checks  │────▶│   Deploy    │
│  (GitHub)   │     │  (Actions)  │     │ (Vercel)    │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼────┐  ┌─────▼────┐
              │   Lint   │  │   Test   │
              │   Type   │  │   Build  │
              └──────────┘  └──────────┘

CI Checks:

• ✅ Linting (ESLint)
• ✅ Type checking (TypeScript)
• ✅ Unit tests (Jest)
• ✅ Integration tests
• ✅ E2E tests (Playwright)
• ✅ Security scans (TruffleHog)
• ✅ Build verification

---

📈 Performance Optimizations

Frontend

• Code Splitting: Dynamic imports, route-based splitting
• Image Optimization: Next.js Image component, Sharp.js
• Bundle Analysis: Webpack Bundle Analyzer
• Lazy Loading: React.lazy for heavy components
• Memoization: React.memo, useMemo, useCallback
• Virtual Scrolling: For long message lists

Backend

• Database Indexes: Optimized indexes for common queries
• Connection Pooling: PgBouncer for PostgreSQL
• Caching: Redis for frequently accessed data
• Query Optimization: Hasura performance hints
• CDN: Static assets on CDN (Cloudflare, etc.)

Monitoring

• Sentry: Error tracking and performance monitoring
• Grafana: Metrics dashboards
• Prometheus: Metrics collection
• Loki: Log aggregation

---

🧪 Testing Strategy

Test Pyramid

           ┌─────────────┐
           │  E2E Tests  │  (Playwright)
           │    ~150     │
           └─────────────┘
          ┌───────────────┐
          │Integration    │  (Jest)
          │   Tests       │
          │    ~250       │
          └───────────────┘
       ┌────────────────────┐
       │   Unit Tests       │  (Jest)
       │     ~600           │
       └────────────────────┘

Coverage Goals:

• Unit Tests: >80%
• Integration Tests: Critical paths
• E2E Tests: User journeys

---

📚 Technology Stack Summary

Frontend

Category	Technology	Version
Framework	Next.js	15.1.6
UI Library	React	19.0.0
Language	TypeScript	5.7.3
Styling	Tailwind CSS	3.4.17
State	Zustand	5.0.3
GraphQL	Apollo Client	3.12.8
UI Components	Radix UI	Latest
Forms	React Hook Form	7.54.2
Validation	Zod	3.24.1

Backend

Category	Technology	Version
Database	PostgreSQL	16
GraphQL	Hasura	2.x
Auth	Nhost Auth	Latest
Storage	MinIO	Latest
Search	MeiliSearch	1.x
Cache	Redis	7.x
Proxy	Nginx	Latest
Infrastructure	nself CLI	0.4.2

Mobile/Desktop

Category	Technology	Version
Mobile	Capacitor	6.2
Desktop	Electron	33.2
Build Tool	Vite	6.0

DevOps

Category	Technology	Purpose
CI/CD	GitHub Actions	Automation
Monitoring	Sentry	Error tracking
Logging	Loki	Log aggregation
Metrics	Prometheus	Metrics collection
Dashboards	Grafana	Visualization

---

🔗 Additional Resources

• Backend README - Backend setup and services
• Frontend README - Frontend monorepo details
• Database Schema - Complete schema documentation
• API Reference - GraphQL API documentation
• Deployment Guide - Production deployment

---

Next Steps: Quick Start | Installation | Deployment