# yahyanaim/architecture architecture

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

- Interactive diagram: https://gitdiagram.com/yahyanaim/architecture
- Repository: https://github.com/yahyanaim/architecture

## Overview

This is a multi-tenant SaaS starter: a React client calls an Express API, middleware establishes identity and tenant scope, controllers validate requests, domain services apply authentication, billing, user, OAuth, and webhook rules, and repositories persist state. Registration creates an organization, subscription, user, and session; later requests return tenant-scoped results. The tree and README document additional routes and adapters whose implementations were not sampled, so those links are kept at their documented entry points rather than inferred in detail.

Main entry points: [`server/api/routes/billingRoutes.ts`](https://github.com/yahyanaim/architecture/blob/main/server/api/routes/billingRoutes.ts) (Billing Routes), [`server/app.ts`](https://github.com/yahyanaim/architecture/blob/main/server/app.ts) (Express API), [`server/infrastructure/repositories/SharedUserRepository.ts`](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/repositories/SharedUserRepository.ts) (Repository Composition), [`src/router.tsx`](https://github.com/yahyanaim/architecture/blob/main/src/router.tsx) (App Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_react_shell["React Shell<br/>[App.tsx]"]
  node_router["App Router<br/>[router.tsx]"]
  node_auth_ui["Auth Features"]
  node_workspace_ui["Workspace Features"]
  node_billing_ui["Billing Features"]
end

subgraph group_api["API Boundary"]
  node_api_server["Express API<br/>[app.ts]"]
  node_auth_routes["Auth Routes<br/>[authRoutes.ts]"]
  node_billing_routes["Billing Routes<br/>[billingRoutes.ts]"]
  node_webhook_controller["Webhook Controller"]
  node_auth_middleware["Access Middleware<br/>[authenticate.ts]"]
  node_tenant_middleware["Tenant Resolution<br/>[resolveTenant.ts]"]
end

subgraph group_domain["Domain Services"]
  node_auth_service["Auth Service<br/>[AuthService.ts]"]
  node_oauth_service["OAuth Service<br/>[OAuthService.ts]"]
  node_billing_service["Billing Service<br/>[BillingService.ts]"]
end

subgraph group_persistence["Persistence Layer"]
  node_repo_composition["Repository Composition"]
  node_sqlite_repositories["SQLite Repositories"]
  node_database[("Application Database<br/>[database.ts]")]
end

subgraph group_integrations["External Integrations"]
  node_token_service["JWT Token Service<br/>[JwtTokenService.ts]"]
  node_job_queue["Durable Job Queue<br/>[queue.ts]"]
  node_webhook_dispatcher["Webhook Dispatcher"]
end

node_user(("User"))
node_oauth_providers["OAuth Providers"]
node_webhook_targets["Webhook Targets"]
node_stripe["Stripe Billing"]

node_user -->|"uses"| node_react_shell
node_react_shell -->|"starts"| node_router
node_router -->|"dispatches"| node_auth_ui
node_router -->|"dispatches"| node_workspace_ui
node_router -->|"dispatches"| node_billing_ui
node_auth_ui -->|"requests"| node_api_server
node_workspace_ui -->|"requests"| node_api_server
node_billing_ui -->|"requests"| node_api_server
node_api_server -->|"mounts"| node_auth_routes
node_api_server -->|"mounts"| node_billing_routes
node_billing_routes -->|"authenticates"| node_auth_middleware
node_billing_routes -->|"resolves tenant"| node_tenant_middleware
node_auth_routes -->|"invokes"| node_auth_service
node_auth_routes -->|"invokes"| node_oauth_service
node_auth_service -->|"persists state"| node_repo_composition
node_auth_service -->|"mints tokens"| node_token_service
node_auth_service -->|"queues emails"| node_job_queue
node_oauth_service -.->|"exchanges codes"| node_oauth_providers
node_oauth_service -->|"links accounts"| node_repo_composition
node_billing_routes -->|"updates billing"| node_billing_service
node_billing_service -->|"stores subscription"| node_repo_composition
node_billing_routes -.->|"reads invoices"| node_stripe
node_webhook_controller -->|"stores endpoints"| node_repo_composition
node_webhook_controller -->|"dispatches delivery"| node_webhook_dispatcher
node_webhook_controller -->|"queues retry"| node_job_queue
node_webhook_dispatcher -.->|"delivers events"| node_webhook_targets
node_repo_composition -->|"selects adapters"| node_sqlite_repositories
node_sqlite_repositories -->|"reads writes"| node_database
node_job_queue -->|"persists jobs"| node_database
node_auth_middleware -->|"verifies tokens"| node_token_service

click node_react_shell "https://github.com/yahyanaim/architecture/blob/main/src/App.tsx"
click node_router "https://github.com/yahyanaim/architecture/blob/main/src/router.tsx"
click node_auth_ui "https://github.com/yahyanaim/architecture/tree/main/src/features/auth"
click node_workspace_ui "https://github.com/yahyanaim/architecture/tree/main/src/features/workspaces"
click node_billing_ui "https://github.com/yahyanaim/architecture/tree/main/src/features/billing"
click node_api_server "https://github.com/yahyanaim/architecture/blob/main/server/app.ts"
click node_auth_routes "https://github.com/yahyanaim/architecture/blob/main/server/api/routes/authRoutes.ts"
click node_billing_routes "https://github.com/yahyanaim/architecture/blob/main/server/api/routes/billingRoutes.ts"
click node_webhook_controller "https://github.com/yahyanaim/architecture/blob/main/server/api/controllers/WebhookController.ts"
click node_auth_middleware "https://github.com/yahyanaim/architecture/blob/main/server/api/middleware/authenticate.ts"
click node_tenant_middleware "https://github.com/yahyanaim/architecture/blob/main/server/api/middleware/resolveTenant.ts"
click node_auth_service "https://github.com/yahyanaim/architecture/blob/main/server/domain/services/AuthService.ts"
click node_oauth_service "https://github.com/yahyanaim/architecture/blob/main/server/domain/services/OAuthService.ts"
click node_billing_service "https://github.com/yahyanaim/architecture/blob/main/server/domain/services/BillingService.ts"
click node_repo_composition "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/repositories/SharedUserRepository.ts"
click node_sqlite_repositories "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/repositories/SqliteUserRepository.ts"
click node_database "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/database.ts"
click node_token_service "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/security/JwtTokenService.ts"
click node_job_queue "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/queue.ts"
click node_webhook_dispatcher "https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/webhooks/WebhookDispatcher.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_react_shell,node_router,node_auth_ui,node_workspace_ui,node_billing_ui,node_user toneBlue
class node_api_server,node_auth_routes,node_billing_routes,node_webhook_controller,node_auth_middleware,node_tenant_middleware toneAmber
class node_auth_service,node_oauth_service,node_billing_service,node_webhook_targets toneMint
class node_repo_composition,node_sqlite_repositories,node_database toneRose
class node_token_service,node_job_queue,node_webhook_dispatcher,node_oauth_providers,node_stripe toneIndigo
```

## Components

### React Client

- [React Shell](https://github.com/yahyanaim/architecture/blob/main/src/App.tsx): `src/App.tsx`
- [App Router](https://github.com/yahyanaim/architecture/blob/main/src/router.tsx): `src/router.tsx`
- [Auth Features](https://github.com/yahyanaim/architecture/tree/main/src/features/auth): `src/features/auth`
- [Workspace Features](https://github.com/yahyanaim/architecture/tree/main/src/features/workspaces): `src/features/workspaces`
- [Billing Features](https://github.com/yahyanaim/architecture/tree/main/src/features/billing): `src/features/billing`

### API Boundary

- [Express API](https://github.com/yahyanaim/architecture/blob/main/server/app.ts): `server/app.ts`
- [Auth Routes](https://github.com/yahyanaim/architecture/blob/main/server/api/routes/authRoutes.ts): `server/api/routes/authRoutes.ts`
- [Billing Routes](https://github.com/yahyanaim/architecture/blob/main/server/api/routes/billingRoutes.ts): `server/api/routes/billingRoutes.ts`
- [Webhook Controller](https://github.com/yahyanaim/architecture/blob/main/server/api/controllers/WebhookController.ts): `server/api/controllers/WebhookController.ts`
- [Access Middleware](https://github.com/yahyanaim/architecture/blob/main/server/api/middleware/authenticate.ts): `server/api/middleware/authenticate.ts`
- [Tenant Resolution](https://github.com/yahyanaim/architecture/blob/main/server/api/middleware/resolveTenant.ts): `server/api/middleware/resolveTenant.ts`

### Domain Services

- [Auth Service](https://github.com/yahyanaim/architecture/blob/main/server/domain/services/AuthService.ts): `server/domain/services/AuthService.ts`
- [OAuth Service](https://github.com/yahyanaim/architecture/blob/main/server/domain/services/OAuthService.ts): `server/domain/services/OAuthService.ts`
- [Billing Service](https://github.com/yahyanaim/architecture/blob/main/server/domain/services/BillingService.ts): `server/domain/services/BillingService.ts`

### Persistence Layer

- [Repository Composition](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/repositories/SharedUserRepository.ts): `server/infrastructure/repositories/SharedUserRepository.ts`
- [SQLite Repositories](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/repositories/SqliteUserRepository.ts): `server/infrastructure/repositories/SqliteUserRepository.ts`
- [Application Database](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/database.ts): `server/infrastructure/database.ts`

### External Integrations

- [JWT Token Service](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/security/JwtTokenService.ts): `server/infrastructure/security/JwtTokenService.ts`
- [Durable Job Queue](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/queue.ts): `server/infrastructure/queue.ts`
- [Webhook Dispatcher](https://github.com/yahyanaim/architecture/blob/main/server/infrastructure/webhooks/WebhookDispatcher.ts): `server/infrastructure/webhooks/WebhookDispatcher.ts`

### Other components

- **User**
- **OAuth Providers**
- **Webhook Targets**
- **Stripe Billing**

## Connections

- User → React Shell: uses
- React Shell → App Router: starts
- App Router → Auth Features: dispatches
- App Router → Workspace Features: dispatches
- App Router → Billing Features: dispatches
- Auth Features → Express API: requests
- Workspace Features → Express API: requests
- Billing Features → Express API: requests
- Express API → Auth Routes: mounts
- Express API → Billing Routes: mounts
- Billing Routes → Access Middleware: authenticates
- Billing Routes → Tenant Resolution: resolves tenant
- Auth Routes → Auth Service: invokes
- Auth Routes → OAuth Service: invokes
- Auth Service → Repository Composition: persists state
- Auth Service → JWT Token Service: mints tokens
- Auth Service → Durable Job Queue: queues emails
- OAuth Service → OAuth Providers: exchanges codes
- OAuth Service → Repository Composition: links accounts
- Billing Routes → Billing Service: updates billing
- Billing Service → Repository Composition: stores subscription
- Billing Routes → Stripe Billing: reads invoices
- Webhook Controller → Repository Composition: stores endpoints
- Webhook Controller → Webhook Dispatcher: dispatches delivery
- Webhook Controller → Durable Job Queue: queues retry
- Webhook Dispatcher → Webhook Targets: delivers events
- Repository Composition → SQLite Repositories: selects adapters
- SQLite Repositories → Application Database: reads writes
- Durable Job Queue → Application Database: persists jobs
- Access Middleware → JWT Token Service: verifies tokens
