Version: 1.0.9 Last Updated: 2026-04-18

ɳChat (nself-chat) is a FOSS team communication platform built as a reference implementation of what can be achieved with the nSelf CLI backend infrastructure. This document describes the architectural decisions, patterns, and setup instructions for both standalone and monorepo deployments.

1. Core Principles
2. System Architecture
3. Deployment Models
4. Per-App RBAC/ACL
5. Authentication Architecture
6. Database Schema
7. Frontend Architecture
8. Backend Services
9. Security Model
10. Monorepo Setup Guide

ɳChat uses nSelf CLI exclusively for all backend operations:

• ✅ Database: PostgreSQL via nSelf
• ✅ GraphQL: Hasura via nSelf
• ✅ Authentication: Nhost Auth via nSelf
• ✅ Storage: MinIO/S3 via nSelf
• ✅ Search: MeiliSearch via nSelf
• ✅ Real-time: WebSocket subscriptions via Hasura

We do NOT use: Custom Express servers, Firebase, Supabase Auth, or any non-nSelf backend services.

The application supports two deployment models:

Standalone

user@host:~$ git clone nself-chat
user@host:~$ cd nself-chat
user@host:~$ nself start
user@host:~$ pnpm dev

One app, one backend, independent deployment.

Monorepo ("One of Many")

monorepo/
├── backend/          # Shared nSelf backend
├── nchat/            # This app
├── ntv/              # Another app
└── nfamily/          # Another app

Multiple apps, one backend, shared authentication, per-app roles.

In monorepo deployments, users authenticate once but can have different roles in different apps:

• Admin in ɳChat, regular user in ɳTV
• Owner in ɳFamily, guest in ɳChat
• Moderator in ɳTV, member in ɳFamily

This is implemented via three PostgreSQL tables:

• apps - Registry of all applications
• app_user_roles - User roles per app
• app_role_permissions - Permissions per role per app

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend Layer                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │   Web    │  │  Mobile  │  │ Desktop  │  │  Admin   │        │
│  │ Next.js  │  │Capacitor │  │ Electron │  │  Panel   │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │             │              │             │              │
│       └─────────────┴──────────────┴─────────────┘              │
│                          │                                       │
└──────────────────────────┼───────────────────────────────────────┘
                           │
                ┌──────────▼──────────┐
                │   Nginx Reverse     │
                │       Proxy         │
                └──────────┬──────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│    Hasura      │ │  Nhost Auth │ │  MinIO Storage  │
│  GraphQL API   │ │   Service   │ │   (S3-compat)   │
└───────┬────────┘ └──────┬──────┘ └────────┬────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                   ┌───────▼────────┐
                   │   PostgreSQL   │
                   │   Database     │
                   └────────────────┘

Frontend

• Framework: Next.js 15.1.6 (App Router)
• UI: React 19 + Radix UI + Tailwind CSS
• State: Zustand + Apollo Client
• Real-time: GraphQL subscriptions + Socket.io
• Editor: TipTap 2.11.2
• Forms: React Hook Form + Zod

Backend (via nSelf CLI)

• Database: PostgreSQL 15+ with 60+ extensions
• GraphQL: Hasura Engine
• Auth: Nhost Authentication
• Storage: MinIO (S3-compatible)
• Search: MeiliSearch
• Cache: Redis
• Monitoring: Grafana + Prometheus + Loki

Use Case: Independent installation, single team/organization.

Directory Structure:

nself-chat/
├── backend/              # nSelf CLI project
│   ├── migrations/       # DB migrations
│   ├── docker-compose.yml
│   └── .env
├── frontend/             # Next.js app
│   ├── src/
│   ├── platforms/
│   └── package.json
└── README.md

Setup:

# 1. Initialize backend
cd backend
nself init
nself start

# 2. Start frontend
cd ../frontend
pnpm install
pnpm dev

Environment:

# frontend/.env.local
NEXT_PUBLIC_APP_ID=nchat
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth
NEXT_PUBLIC_STORAGE_URL=http://storage.localhost/v1/storage

Use Case: Multiple applications sharing authentication and users.

Directory Structure:

monorepo/
├── backend/                # Shared nSelf backend
│   ├── migrations/
│   │   ├── 001_create_users.sql
│   │   ├── 002_add_nchat_tables.sql
│   │   ├── 003_add_ntv_tables.sql
│   │   └── 004_add_per_app_rbac.sql
│   └── docker-compose.yml
├── nchat/                  # ɳChat app
│   ├── frontend/
│   └── package.json
├── ntv/                    # ɳTV app (example)
│   ├── frontend/
│   └── package.json
└── nfamily/                # ɳFamily app (example)
    ├── frontend/
    └── package.json

Setup:

# 1. Initialize shared backend
cd backend
nself init --demo
nself start

# 2. Run migrations for all apps
nself exec postgres psql -U postgres -d nself < migrations/001_create_users.sql
nself exec postgres psql -U postgres -d nself < migrations/002_add_nchat_tables.sql
nself exec postgres psql -U postgres -d nself < migrations/003_add_ntv_tables.sql
nself exec postgres psql -U postgres -d nself < migrations/004_add_per_app_rbac.sql

# 3. Start each app
cd ../nchat/frontend && pnpm dev
cd ../ntv/frontend && pnpm dev --port 3001
cd ../nfamily/frontend && pnpm dev --port 3002

App Environment Configuration:

# nchat/frontend/.env.local
NEXT_PUBLIC_APP_ID=nchat
NEXT_PUBLIC_APP_NAME=ɳChat
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth

# ntv/frontend/.env.local
NEXT_PUBLIC_APP_ID=ntv
NEXT_PUBLIC_APP_NAME=ɳTV
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth

# nfamily/frontend/.env.local
NEXT_PUBLIC_APP_ID=nfamily
NEXT_PUBLIC_APP_NAME=ɳFamily
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth

The per-app RBAC system allows users to have different roles in different applications while sharing a single user account and authentication session.

apps Table

CREATE TABLE public.apps (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    app_id TEXT UNIQUE NOT NULL,        -- 'nchat', 'ntv', 'nfamily'
    app_name TEXT NOT NULL,             -- 'ɳChat', 'ɳTV', 'ɳFamily'
    app_url TEXT,                       -- 'https://chat.nself.org'
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

app_user_roles Table

CREATE TABLE public.app_user_roles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    app_id TEXT NOT NULL REFERENCES apps(app_id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    role TEXT NOT NULL,                 -- 'owner', 'admin', 'moderator', 'member', 'guest'
    granted_by UUID REFERENCES auth.users(id),
    granted_at TIMESTAMPTZ DEFAULT NOW(),
    expires_at TIMESTAMPTZ,             -- Optional expiration
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(app_id, user_id, role)
);

app_role_permissions Table

CREATE TABLE public.app_role_permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    app_id TEXT NOT NULL REFERENCES apps(app_id) ON DELETE CASCADE,
    role TEXT NOT NULL,
    permission TEXT NOT NULL,           -- 'channels.create', 'messages.delete'
    resource TEXT,                      -- Optional: specific resource ID
    created_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(app_id, role, permission, resource)
);

Permissions use dot notation:

• app.admin - Full app administration
• users.manage - User management
• users.ban - Ban users
• channels.create - Create channels
• channels.delete - Delete channels
• messages.send - Send messages
• messages.delete - Delete own messages
• messages.delete.any - Delete any message
• files.upload - Upload files
• settings.manage - Manage app settings
• billing.manage - Manage billing

-- Check if user has role in app
SELECT user_has_app_role(
    'user-uuid',
    'nchat',
    'admin'
);

-- Check if user has permission in app
SELECT user_has_app_permission(
    'user-uuid',
    'nchat',
    'channels.delete',
    NULL  -- resource ID (optional)
);

-- Get all user roles for app
SELECT * FROM get_user_app_roles(
    'user-uuid',
    'nchat'
);

Hook Usage:

import { useAppPermissions } from '@/hooks/use-app-permissions'

function DeleteChannelButton({ channelId }: { channelId: string }) {
  const { hasPermission, isAdmin, loading } = useAppPermissions()

  if (loading) return <Skeleton />
  if (!hasPermission('channels.delete')) return null

  return (
    <button onClick={() => deleteChannel(channelId)}>
      Delete Channel
    </button>
  )
}

Context Access:

import { useAuth } from '@/contexts/auth-context'

function UserProfile() {
  const { user } = useAuth()

  return (
    <div>
      <h2>{user.displayName}</h2>
      <p>Roles in {process.env.NEXT_PUBLIC_APP_NAME}:</p>
      <ul>
        {user.appRoles?.map(role => (
          <li key={role}>{role}</li>
        ))}
      </ul>
    </div>
  )
}

# Get user's roles in current app
query GetUserAppRoles($userId: uuid!, $appId: String!) {
  app_user_roles(
    where: {
      user_id: { _eq: $userId }
      app_id: { _eq: $appId }
      _or: [
        { expires_at: { _is_null: true } }
        { expires_at: { _gt: "now()" } }
      ]
    }
  ) {
    role
    granted_at
    expires_at
  }
}

# Grant a role to a user
mutation GrantUserRole(
  $appId: String!
  $userId: uuid!
  $role: String!
  $grantedBy: uuid
) {
  insert_app_user_roles_one(
    object: {
      app_id: $appId
      user_id: $userId
      role: $role
      granted_by: $grantedBy
    }
  ) {
    id
    role
  }
}

When multiple apps share a backend:

1. User logs in to ɳChat → Nhost creates session
2. User visits ɳTV → Session is valid (same auth service)
3. User visits ɳFamily → Session is valid (same auth service)

All apps use the same:

• auth.users table
• Nhost JWT tokens
• Session storage

While authentication is shared, app context is unique:

// User logs in once
user.id = "123"
user.email = "[email protected]"

// Context varies by app
// In ɳChat:
user.appRoles = ["admin"]
user.appContext.permissions = ["channels.delete", "users.ban"]

// In ɳTV (same user):
user.appRoles = ["member"]
user.appContext.permissions = ["videos.view", "videos.upload"]

// In ɳFamily (same user):
user.appRoles = ["owner"]
user.appContext.permissions = ["*"]  // All permissions

For local development, ɳChat supports a test authentication mode:

# Enable test auth (8 predefined users)
NEXT_PUBLIC_USE_DEV_AUTH=true

Test users:

• [email protected] (owner role)
• [email protected] (admin role)
• [email protected] (moderator role)
• [email protected] (member role)
• [email protected] (guest role)

Password for all: password123

IMPORTANT: Never use NEXT_PUBLIC_USE_DEV_AUTH=true in production!

Standalone:

cd backend
nself exec postgres psql -U postgres -d nself < migrations/init.sql

Monorepo:

# Order matters - run in sequence
cd backend
nself exec postgres psql -U postgres -d nself < migrations/001_create_users.sql
nself exec postgres psql -U postgres -d nself < migrations/002_add_per_app_rbac.sql
nself exec postgres psql -U postgres -d nself < migrations/003_add_nchat_tables.sql
nself exec postgres psql -U postgres -d nself < migrations/004_add_ntv_tables.sql

All tables use RLS policies:

-- Example: Messages are viewable by channel members
CREATE POLICY "Users can view messages in their channels"
ON nchat_messages FOR SELECT
USING (
    channel_id IN (
        SELECT channel_id FROM nchat_channel_members
        WHERE user_id = auth.uid()
    )
);

-- Example: Apps are viewable by active app users
CREATE POLICY "Users can view their app roles"
ON app_user_roles FOR SELECT
USING (user_id = auth.uid());

frontend/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes
│   │   ├── auth/              # Auth pages
│   │   ├── chat/              # Main chat UI
│   │   ├── setup/             # Setup wizard
│   │   └── settings/          # User settings
│   ├── components/
│   │   ├── chat/              # Chat components
│   │   ├── ui/                # Radix UI wrappers
│   │   └── layout/            # Header, Sidebar
│   ├── contexts/
│   │   ├── auth-context.tsx   # Auth state
│   │   └── app-config-context.tsx
│   ├── hooks/
│   │   ├── use-channels.ts
│   │   ├── use-messages.ts
│   │   └── use-app-permissions.ts  # RBAC hook
│   ├── graphql/
│   │   ├── queries/
│   │   ├── mutations/
│   │   └── app-rbac.ts        # RBAC queries
│   ├── types/
│   │   ├── app-rbac.ts        # RBAC types
│   │   └── index.ts
│   └── lib/
│       ├── apollo-client.ts
│       └── utils.ts
├── platforms/
│   ├── mobile/                # Capacitor (iOS/Android)
│   ├── desktop/               # Electron/Tauri
│   └── README.md
├── public/                    # Static assets
├── tests/                     # Jest + Playwright
└── package.json

Global State (Zustand):

• User preferences
• Theme settings
• UI state (modals, sidebars)

Server State (Apollo Client):

• Channels
• Messages
• Users
• App configuration

Real-time (GraphQL Subscriptions):

subscription OnNewMessage($channelId: uuid!) {
  nchat_messages(
    where: { channel_id: { _eq: $channelId } }
    order_by: { created_at: desc }
    limit: 1
  ) {
    id
    content
    user {
      id
      displayName
      avatarUrl
    }
    created_at
  }
}

Frontend ─┬─> Hasura (8080) ────> PostgreSQL (5432)
          ├─> Auth (4000) ───────> PostgreSQL (5432)
          ├─> MinIO (9000) ──────> S3 buckets
          └─> MeiliSearch (7700) ─> Search indices

All services run via Docker Compose generated by nSelf CLI:

cd backend
nself start        # Start all services
nself stop         # Stop all services
nself status       # Show status
nself logs hasura  # View logs
nself urls         # List all service URLs

1. User submits credentials → Frontend sends to Nhost Auth
2. Nhost validates → Returns JWT access token + refresh token
3. Frontend stores tokens → Secure HTTP-only cookies (production)
4. Subsequent requests → Include JWT in Authorization header
5. Hasura validates JWT → Decodes user ID, enforces RLS

Layer 1: Hasura JWT Validation

• All requests include JWT
• Hasura verifies signature
• Extracts x-hasura-user-id and x-hasura-role

Layer 2: Row-Level Security (RLS)

• PostgreSQL policies enforce data access
• Uses auth.uid() from JWT claims
• Cannot be bypassed by GraphQL

Layer 3: Application Permissions (RBAC)

• Frontend checks app_user_roles and app_role_permissions
• UI hides/disables unauthorized actions
• Backend validates via RLS policies

# Hasura console > API Limits
api_limits:
  depth_limit:
    global: 10
    per_role:
      user: 7
      anonymous: 5
  node_limit:
    global: 50
    per_role:
      user: 30
      anonymous: 10
  rate_limit:
    global:
      max_reqs_per_min: 120
      unique_params: IP
    per_role:
      user:
        max_reqs_per_min: 60
        unique_params: ["x-hasura-user-id"]

mkdir -p monorepo/{backend,nchat,ntv,nfamily}
cd monorepo

cd backend
nself init --demo
# Follow prompts:
# - Enable: PostgreSQL, Hasura, Auth, MinIO, MeiliSearch, Redis
# - Enable: Monitoring (Grafana + Prometheus + Loki)
# - Set admin password
# - Configure domain (e.g., api.localhost)

cd ..
git clone https://github.com/nself/nself-chat.git nchat
git clone https://github.com/nself/nself-tv.git ntv
git clone https://github.com/nself/nself-family.git nfamily

cd backend

# Core tables (users, auth)
nself exec postgres psql -U postgres -d nself < ../nchat/backend/db/migrations/20260212_add_per_app_rbac.sql

# App-specific tables
nself exec postgres psql -U postgres -d nself < ../nchat/backend/db/migrations/init_nchat.sql
nself exec postgres psql -U postgres -d nself < ../ntv/backend/db/migrations/init_ntv.sql
nself exec postgres psql -U postgres -d nself < ../nfamily/backend/db/migrations/init_nfamily.sql

# ɳChat
cd ../nchat/frontend
cp .env.example .env.local
# Edit NEXT_PUBLIC_APP_ID=nchat

# ɳTV
cd ../../ntv/frontend
cp .env.example .env.local
# Edit NEXT_PUBLIC_APP_ID=ntv

# ɳFamily
cd ../../nfamily/frontend
cp .env.example .env.local
# Edit NEXT_PUBLIC_APP_ID=nfamily

# Terminal 1: Backend
cd backend
nself start

# Terminal 2: ɳChat
cd nchat/frontend
pnpm dev

# Terminal 3: ɳTV
cd ntv/frontend
pnpm dev --port 3001

# Terminal 4: ɳFamily
cd nfamily/frontend
pnpm dev --port 3002

Visit Hasura console (http://localhost:8080) and run:

INSERT INTO public.apps (app_id, app_name, app_url, is_active) VALUES
  ('nchat', 'ɳChat', 'http://localhost:3000', true),
  ('ntv', 'ɳTV', 'http://localhost:3001', true),
  ('nfamily', 'ɳFamily', 'http://localhost:3002', true);

-- Make first user an owner in all apps
INSERT INTO public.app_user_roles (app_id, user_id, role) VALUES
  ('nchat', 'user-uuid-here', 'owner'),
  ('ntv', 'user-uuid-here', 'owner'),
  ('nfamily', 'user-uuid-here', 'owner');

Solution: Assign default role to new users via trigger:

CREATE OR REPLACE FUNCTION assign_default_app_role()
RETURNS TRIGGER AS $$
BEGIN
  -- Assign 'member' role in all active apps
  INSERT INTO public.app_user_roles (app_id, user_id, role)
  SELECT app_id, NEW.id, 'member'
  FROM public.apps
  WHERE is_active = true;

  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER on_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW
  EXECUTE FUNCTION assign_default_app_role();

Solution: Grant Hasura access:

GRANT SELECT ON public.app_user_roles TO hasura;
GRANT SELECT ON public.app_role_permissions TO hasura;
GRANT EXECUTE ON FUNCTION public.user_has_app_role TO hasura;
GRANT EXECUTE ON FUNCTION public.user_has_app_permission TO hasura;

Solution: Track tables in Hasura:

cd backend
nself exec hasura hasura-cli metadata reload

Or via console:

1. Visit http://localhost:8080
2. Data tab → Schema → public
3. Track tables: apps, app_user_roles, app_role_permissions

• nSelf CLI Documentation
• ɳChat README
• Hasura Docs
• Nhost Auth Docs
• GraphQL Best Practices

v0.9.2 (February 12, 2026)

• Added per-app RBAC/ACL system
• Updated README with FOSS mission
• Created ARCHITECTURE.md
• Added monorepo setup documentation

v0.9.0 (February 6, 2026)

• Restructured frontend to nself-family pattern
• Fixed all TypeScript errors
• Achieved 98%+ test pass rate
• Production-ready build

MIT License - See LICENSE file for details.

Questions? Open an issue on GitHub.