# seba-cod3/saas-template architecture

> Architecture diagram of the GitHub repository seba-cod3/saas-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seba-cod3/saas-template
- Repository: https://github.com/seba-cod3/saas-template

## Overview

This is an in-development SaaS starter: users enter through a React SPA, authenticate, and access protected dashboard, admin, and AI-chat screens backed by a Hono API. The server also exposes asset and health routes, plus shared realtime and background-job capabilities. AI conversations persist in PostgreSQL; the README documents Redis-backed resumable streaming, job queues, caching, and Pub/Sub, alongside email and configurable asset storage. The graph uses documented capabilities where implementation excerpts were unavailable; those integration links are dashed.

Main entry points: [`apps/server/src/index.ts`](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/index.ts) (Hono server), [`apps/web/src/main.tsx`](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/main.tsx) (Web SPA), [`apps/server/src/routes/ai.ts`](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/ai.ts) (AI routes), [`apps/server/src/lib/ai/chat-service.ts`](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/ai/chat-service.ts) (Conversation service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web SPA<br/>[main.tsx]"]
  node_authui["Auth UI<br/>[auth-modal.tsx]"]
  node_protected["Protected routes<br/>[_authenticated.tsx]"]
  node_chatui["Chat screens<br/>[chat.tsx]"]
  node_adminui["Admin screens<br/>[admin.tsx]"]
  node_websocketclient["WebSocket client<br/>[ws.ts]"]
end

subgraph group_api["API and domain"]
  node_server["Hono server<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_adminroutes["Admin routes<br/>[admin.ts]"]
  node_airoutes["AI routes<br/>[ai.ts]"]
  node_assetroutes["Asset routes<br/>[assets.ts]"]
  node_healthroutes["Health routes<br/>[health.ts]"]
  node_chatservice["Conversation service<br/>[chat-service.ts]"]
end

subgraph group_services["Runtime services"]
  node_storage["Asset storage<br/>[index.ts]"]
  node_jobs["Job workers<br/>[index.ts]"]
  node_queue["Job queue<br/>[queue.ts]"]
  node_ws["Realtime hub<br/>[ws.ts]"]
end

subgraph group_data["State and providers"]
  node_postgres[("PostgreSQL<br/>[index.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
  node_aiproviders["AI providers"]
  node_objectstore["S3 or local store"]
  node_smtp["SMTP service"]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"opens auth"| node_authui
node_webapp -->|"navigates"| node_protected
node_protected -->|"subscribes"| node_websocketclient
node_webapp -->|"opens chat"| node_chatui
node_webapp -->|"opens admin"| node_adminui
node_authui -->|"signs in"| node_auth
node_webapp -->|"API requests"| node_server
node_server -->|"mounts auth"| node_auth
node_server -->|"dispatches"| node_adminroutes
node_server -->|"dispatches"| node_airoutes
node_server -->|"dispatches"| node_assetroutes
node_server -->|"dispatches"| node_healthroutes
node_airoutes -->|"manages conversations"| node_chatservice
node_chatservice -->|"reads and writes"| node_postgres
node_auth -->|"persists identity"| node_postgres
node_server -->|"handles sockets"| node_ws
node_ws -->|"pushes events"| node_websocketclient
node_server -->|"starts workers"| node_jobs
node_jobs -->|"registers jobs"| node_queue
node_queue -.->|"queues work"| node_redis
node_chatservice -.->|"resumes streams"| node_redis
node_ws -.->|"pub/sub"| node_redis
node_assetroutes -->|"handles assets"| node_storage
node_storage -.->|"stores files"| node_objectstore
node_jobs -.->|"sends email"| node_smtp
node_airoutes -.->|"streams completions"| node_aiproviders

click node_webapp "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/main.tsx"
click node_authui "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/components/auth-modal.tsx"
click node_protected "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated.tsx"
click node_chatui "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated/chat.tsx"
click node_adminui "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated/admin.tsx"
click node_websocketclient "https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/lib/ws.ts"
click node_server "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/index.ts"
click node_auth "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/auth.ts"
click node_adminroutes "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/admin.ts"
click node_airoutes "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/ai.ts"
click node_assetroutes "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/assets.ts"
click node_healthroutes "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/health.ts"
click node_chatservice "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/ai/chat-service.ts"
click node_storage "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/storage/index.ts"
click node_jobs "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/jobs/index.ts"
click node_queue "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/queue.ts"
click node_ws "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/ws.ts"
click node_postgres "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/db/index.ts"
click node_redis "https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/redis.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_authui,node_protected,node_chatui,node_adminui,node_websocketclient,node_user toneBlue
class node_server,node_auth,node_adminroutes,node_airoutes,node_assetroutes,node_healthroutes,node_chatservice toneAmber
class node_storage,node_jobs,node_queue,node_ws toneMint
class node_postgres,node_redis,node_aiproviders,node_objectstore,node_smtp toneRose
```

## Components

### Web application

- [Web SPA](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Auth UI](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/components/auth-modal.tsx): `apps/web/src/components/auth-modal.tsx`
- [Protected routes](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated.tsx): `apps/web/src/routes/_authenticated.tsx`
- [Chat screens](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated/chat.tsx): `apps/web/src/routes/_authenticated/chat.tsx`
- [Admin screens](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/routes/_authenticated/admin.tsx): `apps/web/src/routes/_authenticated/admin.tsx`
- [WebSocket client](https://github.com/seba-cod3/saas-template/blob/main/apps/web/src/lib/ws.ts): `apps/web/src/lib/ws.ts`

### API and domain

- [Hono server](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/index.ts): `apps/server/src/index.ts`
- [Authentication](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/auth.ts): `apps/server/src/lib/auth.ts`
- [Admin routes](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/admin.ts): `apps/server/src/routes/admin.ts`
- [AI routes](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/ai.ts): `apps/server/src/routes/ai.ts`
- [Asset routes](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/assets.ts): `apps/server/src/routes/assets.ts`
- [Health routes](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/routes/health.ts): `apps/server/src/routes/health.ts`
- [Conversation service](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/ai/chat-service.ts): `apps/server/src/lib/ai/chat-service.ts`

### Runtime services

- [Asset storage](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/storage/index.ts): `apps/server/src/lib/storage/index.ts`
- [Job workers](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/jobs/index.ts): `apps/server/src/jobs/index.ts`
- [Job queue](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/queue.ts): `apps/server/src/lib/queue.ts`
- [Realtime hub](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/ws.ts): `apps/server/src/lib/ws.ts`

### State and providers

- [PostgreSQL](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/db/index.ts): `apps/server/src/db/index.ts`
- [Redis](https://github.com/seba-cod3/saas-template/blob/main/apps/server/src/lib/redis.ts): `apps/server/src/lib/redis.ts`
- **AI providers**
- **S3 or local store**
- **SMTP service**

### Other components

- **User**

## Connections

- User → Web SPA: uses
- Web SPA → Auth UI: opens auth
- Web SPA → Protected routes: navigates
- Protected routes → WebSocket client: subscribes
- Web SPA → Chat screens: opens chat
- Web SPA → Admin screens: opens admin
- Auth UI → Authentication: signs in
- Web SPA → Hono server: API requests
- Hono server → Authentication: mounts auth
- Hono server → Admin routes: dispatches
- Hono server → AI routes: dispatches
- Hono server → Asset routes: dispatches
- Hono server → Health routes: dispatches
- AI routes → Conversation service: manages conversations
- Conversation service → PostgreSQL: reads and writes
- Authentication → PostgreSQL: persists identity
- Hono server → Realtime hub: handles sockets
- Realtime hub → WebSocket client: pushes events
- Hono server → Job workers: starts workers
- Job workers → Job queue: registers jobs
- Job queue → Redis: queues work
- Conversation service → Redis: resumes streams
- Realtime hub → Redis: pub/sub
- Asset routes → Asset storage: handles assets
- Asset storage → S3 or local store: stores files
- Job workers → SMTP service: sends email
- AI routes → AI providers: streams completions