# mrgharbiii/slim-express architecture

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

- Interactive diagram: https://gitdiagram.com/mrgharbiii/slim-express
- Repository: https://github.com/mrgharbiii/slim-express

## Overview

1. This is a Node.js/Express backend organized as a layered API service. `src/app.js` is the composition root: it wires middleware, route registration, configuration, and global error handling into a single server process.

2. The external interface is REST-style HTTP under the `/api` namespace. Route modules are split by domain: `auth`, `users`, `admin`, `ai`, `analysis`, `onboarding`, and `health`. That separation is the main architectural boundary for the API surface.

3. Request handling follows a standard pipeline:
   - route module matches the endpoint,
   - middleware performs auth/validation/security checks,
   - controller implements request/response behavior,
   - service layer handles non-trivial business logic,
   - model/config layers interact with persistence or infrastructure.

4. Authentication is a first-class subsystem. `src/utils/jwt.js` provides token utilities, `src/middleware/auth.js` protects private routes, and `src/controllers/authController.js` owns login/register/session-related behavior. The presence of `docs/authentication.md` suggests auth flows are documented and likely central to the API design.

5. Persistence is abstracted through `src/config/database.js` and `src/models/User.js`. The repository structure implies a data-backed API, with `User` as the primary domain model currently visible. The exact database engine is not shown here, but the architecture clearly separates database setup from request handling.

6. AI functionality is isolated rather than embedded throughout the app. `src/controllers/aiController.js` and `src/services/aiService.js` indicate a controller-to-service boundary for AI-related operations, and `docs/ai-integration.md` suggests that this subsystem talks to an external AI provider or API rather than implementing AI logic locally.

7. The analysis and onboarding areas look like business-domain modules on top of the core auth/data foundation. `analysisController`, `onboardingController`, and `middleware/labValidation.js` indicate domain-specific workflows and validation rules, likely tied to a structured intake or assessment process.

8. Admin capabilities are separated into `src/routes/admin.js` and `src/controllers/adminController.js`, which usually means privileged operations are isolated from the public user flow. This boundary is likely enforced by the auth middleware and role/permission checks, even if those details are not visible from the file tree alone.

9. Cross-cutting concerns are handled centrally:
   - `src/config/security.js` for security-related Express setup,
   - `src/middleware/validation.js` and `labValidation.js` for request validation,
   - `src/middleware/errorHandler.js` for unified error responses.
   This keeps controllers focused on domain logic and prevents duplicated guard code.

10. Operationally, the repo is built for a lightweight service lifecycle: Yarn scripts for dev/prod/test, Nodemon for hot reload, Jest for tests, dotenv for environment configuration, and common Express middleware like Helmet, CORS, and Morgan as noted in the README. `tests/app.test.js` suggests at least one integration-level test around the app bootstrap or health surface.

11. `src/types/user.types.ts` is notable because it introduces TypeScript type definitions into an otherwise JavaScript service. That usually means the codebase is using typed contracts for shared domain shapes without being fully TypeScript-based.

12. For an architecture diagram, the key boxes are: HTTP API entrypoint, route layer, controller layer, service layer, auth/validation/security middleware, persistence/database, and external AI integration. The main flows are public/admin/authenticated requests through middleware into controllers, and AI-specific requests from controllers into the AI service and out to an external provider.

Main entry points: [`src/app.js`](https://github.com/mrgharbiii/slim-express/blob/main/src/app.js) (App), [`src/middleware/auth.js`](https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/auth.js) (Auth middleware), [`src/routes/analysis.js`](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/analysis.js) (Analysis routes), [`src/routes/onboarding.js`](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/onboarding.js) (Onboarding routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoint"]
  node_app["App<br/>Express bootstrap<br/>[app.js]"]
end

subgraph group_api["API surface"]
  node_auth_route["Auth routes<br/>route module<br/>[auth.js]"]
  node_users_route["User routes<br/>route module<br/>[users.js]"]
  node_admin_route["Admin routes<br/>route module<br/>[admin.js]"]
  node_ai_route["AI routes<br/>route module<br/>[ai.js]"]
  node_analysis_route["Analysis routes<br/>route module<br/>[analysis.js]"]
  node_onboarding_route["Onboarding routes<br/>route module<br/>[onboarding.js]"]
  node_health_route["Health routes<br/>route module<br/>[health.js]"]
end

subgraph group_appflow["Request flow"]
  node_auth_controller["Auth controller<br/>[authController.js]"]
  node_admin_controller["Admin controller<br/>[adminController.js]"]
  node_ai_controller["AI controller<br/>[aiController.js]"]
  node_analysis_controller["Analysis controller"]
  node_onboarding_controller["Onboarding controller"]
  node_ai_service["AI service<br/>[aiService.js]"]
  node_auth_mw["Auth middleware<br/>[auth.js]"]
  node_validation_mw["Validation middleware<br/>[validation.js]"]
  node_lab_validation_mw["Lab validation<br/>middleware<br/>[labValidation.js]"]
  node_error_handler["Error handler<br/>middleware<br/>[errorHandler.js]"]
end

subgraph group_infra["Infrastructure"]
  node_db_config[("Database<br/>config<br/>[database.js]")]
  node_security_config["Security config<br/>[security.js]"]
  node_user_model["User model<br/>[User.js]"]
  node_jwt_utils["JWT utils<br/>[jwt.js]"]
  node_user_types["User types<br/>[user.types.ts]"]
end

node_app -->|"mounts"| node_auth_route
node_app -->|"mounts"| node_users_route
node_app -->|"mounts"| node_admin_route
node_app -->|"mounts"| node_ai_route
node_app -->|"mounts"| node_analysis_route
node_app -->|"mounts"| node_onboarding_route
node_app -->|"mounts"| node_health_route
node_app -->|"applies"| node_security_config
node_app -->|"uses"| node_error_handler
node_auth_route -->|"protects"| node_auth_mw
node_auth_route -->|"handles"| node_auth_controller
node_users_route -->|"protects"| node_auth_mw
node_users_route -->|"validates"| node_validation_mw
node_admin_route -->|"protects"| node_auth_mw
node_admin_route -->|"handles"| node_admin_controller
node_ai_route -->|"protects"| node_auth_mw
node_ai_route -->|"handles"| node_ai_controller
node_analysis_route -->|"protects"| node_auth_mw
node_analysis_route -->|"handles"| node_analysis_controller
node_analysis_route -->|"validates"| node_lab_validation_mw
node_onboarding_route -->|"protects"| node_auth_mw
node_onboarding_route -->|"handles"| node_onboarding_controller
node_onboarding_route -->|"validates"| node_validation_mw
node_ai_controller -->|"delegates"| node_ai_service
node_ai_service -.->|"auth helpers"| node_jwt_utils
node_auth_controller -->|"issues tokens"| node_jwt_utils
node_auth_controller -->|"persists"| node_user_model
node_user_model -->|"uses"| node_db_config
node_auth_mw -->|"verifies"| node_jwt_utils
node_auth_controller -.->|"shares contracts"| node_user_types
node_analysis_controller -->|"reads"| node_user_model
node_onboarding_controller -->|"updates"| node_user_model

click node_app "https://github.com/mrgharbiii/slim-express/blob/main/src/app.js"
click node_auth_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/auth.js"
click node_users_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/users.js"
click node_admin_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/admin.js"
click node_ai_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/ai.js"
click node_analysis_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/analysis.js"
click node_onboarding_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/onboarding.js"
click node_health_route "https://github.com/mrgharbiii/slim-express/blob/main/src/routes/health.js"
click node_auth_controller "https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/authController.js"
click node_admin_controller "https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/adminController.js"
click node_ai_controller "https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/aiController.js"
click node_analysis_controller "https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/analysisController.js"
click node_onboarding_controller "https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/onboardingController.js"
click node_ai_service "https://github.com/mrgharbiii/slim-express/blob/main/src/services/aiService.js"
click node_auth_mw "https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/auth.js"
click node_validation_mw "https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/validation.js"
click node_lab_validation_mw "https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/labValidation.js"
click node_error_handler "https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/errorHandler.js"
click node_db_config "https://github.com/mrgharbiii/slim-express/blob/main/src/config/database.js"
click node_security_config "https://github.com/mrgharbiii/slim-express/blob/main/src/config/security.js"
click node_user_model "https://github.com/mrgharbiii/slim-express/blob/main/src/models/User.js"
click node_jwt_utils "https://github.com/mrgharbiii/slim-express/blob/main/src/utils/jwt.js"
click node_user_types "https://github.com/mrgharbiii/slim-express/blob/main/src/types/user.types.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_app toneBlue
class node_auth_route,node_users_route,node_admin_route,node_ai_route,node_analysis_route,node_onboarding_route,node_health_route toneAmber
class node_auth_controller,node_admin_controller,node_ai_controller,node_analysis_controller,node_onboarding_controller,node_ai_service,node_auth_mw,node_validation_mw,node_lab_validation_mw,node_error_handler toneMint
class node_db_config,node_security_config,node_user_model,node_jwt_utils,node_user_types toneRose
```

## Components

### Entrypoint

Server bootstrap and process wiring

- [App](https://github.com/mrgharbiii/slim-express/blob/main/src/app.js): Express bootstrap · Composition root that wires middleware, routes, config, and error handling · `src/app.js`

### API surface

REST route modules grouped by domain

- [Auth routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/auth.js): route module · Authentication endpoints under the API namespace · `src/routes/auth.js`
- [User routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/users.js): route module · User-facing API endpoints · `src/routes/users.js`
- [Admin routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/admin.js): route module · Privileged administrative endpoints · `src/routes/admin.js`
- [AI routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/ai.js): route module · AI-related API endpoints · `src/routes/ai.js`
- [Analysis routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/analysis.js): route module · Analysis workflow endpoints · `src/routes/analysis.js`
- [Onboarding routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/onboarding.js): route module · Onboarding and intake endpoints · `src/routes/onboarding.js`
- [Health routes](https://github.com/mrgharbiii/slim-express/blob/main/src/routes/health.js): route module · Service health and readiness endpoints · `src/routes/health.js`

### Request flow

Controllers, middleware, and services that handle requests

- [Auth controller](https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/authController.js): controller · Login, register, and session behavior · `src/controllers/authController.js`
- [Admin controller](https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/adminController.js): controller · Administrative request handling · `src/controllers/adminController.js`
- [AI controller](https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/aiController.js): controller · AI request handling and response shaping · `src/controllers/aiController.js`
- [Analysis controller](https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/analysisController.js): controller · Analysis workflow orchestration · `src/controllers/analysisController.js`
- [Onboarding controller](https://github.com/mrgharbiii/slim-express/blob/main/src/controllers/onboardingController.js): controller · Onboarding workflow orchestration · `src/controllers/onboardingController.js`
- [AI service](https://github.com/mrgharbiii/slim-express/blob/main/src/services/aiService.js): service · Business logic boundary for AI integration · `src/services/aiService.js`
- [Auth middleware](https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/auth.js): middleware · Protects private routes with token checks · `src/middleware/auth.js`
- [Validation middleware](https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/validation.js): middleware · Shared request validation rules · `src/middleware/validation.js`
- [Lab validation](https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/labValidation.js): middleware · Domain-specific validation for lab or intake flows · `src/middleware/labValidation.js`
- [Error handler](https://github.com/mrgharbiii/slim-express/blob/main/src/middleware/errorHandler.js): middleware · Unified API error responses · `src/middleware/errorHandler.js`

### Infrastructure

Configuration, persistence, and shared utilities

- [Database](https://github.com/mrgharbiii/slim-express/blob/main/src/config/database.js): config · Database setup and connection configuration · `src/config/database.js`
- [Security config](https://github.com/mrgharbiii/slim-express/blob/main/src/config/security.js): config · Express security-related configuration · `src/config/security.js`
- [User model](https://github.com/mrgharbiii/slim-express/blob/main/src/models/User.js): model · Primary persisted user domain model · `src/models/User.js`
- [JWT utils](https://github.com/mrgharbiii/slim-express/blob/main/src/utils/jwt.js): utility · Token creation and verification helpers · `src/utils/jwt.js`
- [User types](https://github.com/mrgharbiii/slim-express/blob/main/src/types/user.types.ts): types · Shared TypeScript user contracts · `src/types/user.types.ts`

## Connections

- App → Auth routes: mounts · Registers auth endpoints
- App → User routes: mounts · Registers user endpoints
- App → Admin routes: mounts · Registers admin endpoints
- App → AI routes: mounts · Registers AI endpoints
- App → Analysis routes: mounts · Registers analysis endpoints
- App → Onboarding routes: mounts · Registers onboarding endpoints
- App → Health routes: mounts · Registers health endpoints
- App → Security config: applies · Installs security-related Express setup
- App → Error handler: uses · Ends the pipeline with unified errors
- Auth routes → Auth middleware: protects · Applies token checks where needed
- Auth routes → Auth controller: handles · Delegates auth actions to controller
- User routes → Auth middleware: protects · Requires authentication for user operations
- User routes → Validation middleware: validates · Checks request payloads
- Admin routes → Auth middleware: protects · Restricts admin access
- Admin routes → Admin controller: handles · Delegates admin operations
- AI routes → Auth middleware: protects · Secures AI endpoints
- AI routes → AI controller: handles · Delegates AI requests
- Analysis routes → Auth middleware: protects · Secures analysis endpoints
- Analysis routes → Analysis controller: handles · Delegates analysis workflow
- Analysis routes → Lab validation: validates · Applies domain-specific intake checks
- Onboarding routes → Auth middleware: protects · Secures onboarding flow
- Onboarding routes → Onboarding controller: handles · Delegates onboarding workflow
- Onboarding routes → Validation middleware: validates · Applies shared request validation
- AI controller → AI service: delegates · Hands off non-trivial AI logic
- AI service → JWT utils: auth helpers · May rely on shared token utilities when needed
- Auth controller → JWT utils: issues tokens · Creates and verifies auth tokens
- Auth controller → User model: persists · Reads and writes user records
- User model → Database: uses · Connects model data to the database
- Auth middleware → JWT utils: verifies · Checks bearer tokens
- Auth controller → User types: shares contracts · Uses typed user shapes across layers
- Analysis controller → User model: reads · Uses user data for analysis flows
- Onboarding controller → User model: updates · Stores onboarding progress
