# 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](https://nself.org) 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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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**:

```typescript
// 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](./ARCHITECTURE.md) - Backend setup and services
- [Frontend README](./Architecture-Overview.md) - Frontend monorepo details
- [Database Schema](reference/Database-Schema.md) - Complete schema documentation
- [API Reference](api/API.md) - GraphQL API documentation
- [Deployment Guide](DEPLOYMENT-GUIDE.md) - Production deployment

---

**Next Steps**: [Quick Start](nself-cli/Quick-Start.md) | [Installation](getting-started/Installation.md) | [Deployment](DEPLOYMENT-GUIDE.md)