# flatwhite-dev/jwtauth-template- architecture

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

- Interactive diagram: https://gitdiagram.com/flatwhite-dev/jwtauth-template-
- Repository: https://github.com/flatwhite-dev/jwtauth-template-

## Overview

1. **Repository shape**
   - This is a two-part auth template: a **React + TypeScript client** in `client/` and a **Node.js backend** in `server/`.
   - The overall purpose is JWT-based authentication with user activation, not a general-purpose business app.

2. **Client-side presentation layer**
   - The client is a single-page app bootstrapped from `client/src/index.tsx` and `client/src/App.tsx`.
   - UI is centered around two forms: `LoginForm.tsx` and `ActivateForm.tsx`, which suggests a login flow plus email/account activation flow.

3. **Client-side state and domain models**
   - `client/src/store/UserStore.ts` is the main auth state boundary on the frontend.
   - `client/src/models/IUser.ts` and `client/src/models/response/AuthResponse.ts` define the data contract the UI expects from the backend.

4. **Client API layer**
   - `client/src/http/index.ts` is the shared HTTP client boundary for all server communication.
   - `client/src/services/AuthService.ts` and `client/src/services/UserService.ts` separate authentication requests from user/profile-related requests, keeping components thin.

5. **Backend entrypoint and routing**
   - The server starts from `server/index.js`.
   - `server/routes/index.js` is the main request router, likely mounting user/auth endpoints under a common API namespace.

6. **Backend controller layer**
   - `server/controllers/user-controller.js` is the main HTTP-facing controller.
   - It translates requests/responses between Express and the service layer, so business logic is not embedded in route handlers.

7. **Backend domain and auth services**
   - `server/service/user-service.js` contains the core user/auth workflow.
   - `server/service/token-service.js` handles token creation/validation, which is central to the JWT architecture.
   - `server/service/mail-service.js` indicates activation emails or similar outbound notifications are part of the flow.

8. **Persistence model boundary**
   - `server/models/user-model.js` and `server/models/token-model.js` represent stored entities for users and tokens.
   - The presence of model files strongly suggests a database-backed design, with tokens persisted separately from users.

9. **DTOs and error handling**
   - `server/dtos/user-dto.js` is a transfer layer that shapes user data before it crosses the API boundary.
   - `server/exceptions/api-error.js`, `server/exceptions/errors.js`, and `server/middlewares/error-middleware.js` centralize error normalization and response formatting.

10. **Security boundary**
   - `server/middlewares/auth-middleware.js` protects routes by validating incoming auth state, likely using JWTs from the client.
   - This creates the key trust boundary: unauthenticated requests are rejected before reaching business logic.

11. **End-to-end auth flow**
   - A user interacts with the React forms, which call the shared HTTP layer.
   - The backend controller delegates to the auth/user services.
   - The services create/verify tokens, update persisted user/token records, and may send activation mail.
   - The server returns an auth response that the frontend stores in `UserStore`.

12. **Operational/configuration clues**
   - `server/.env.example` shows the backend relies on environment-based configuration for secrets and service settings.
   - Both sides use standard npm-based JavaScript/TypeScript tooling, but the architecture is simple: a frontend SPA talks directly to a dedicated auth API.

Main entry points: [`server/service/user-service.js`](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/user-service.js) (User Service), [`client/src/App.tsx`](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/App.tsx) (App), [`server/controllers/user-controller.js`](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/controllers/user-controller.js) (User Controller), [`client/src/services/AuthService.ts`](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/services/AuthService.ts) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_index(("Entry<br/>React bootstrap<br/>[index.tsx]"))
  node_client_app["App<br/>SPA shell<br/>[App.tsx]"]
  node_client_login_form["Login Form<br/>auth UI<br/>[LoginForm.tsx]"]
  node_client_activate_form["Activate Form<br/>activation UI<br/>[ActivateForm.tsx]"]
  node_client_user_store[("User Store<br/>auth state<br/>[UserStore.ts]")]
  node_client_http["HTTP Client<br/>api client<br/>[index.ts]"]
  node_client_auth_service["Auth Service<br/>auth api<br/>[AuthService.ts]"]
  node_client_user_service["User Service<br/>user api<br/>[UserService.ts]"]
  node_client_user_model["User Model<br/>domain model<br/>[IUser.ts]"]
  node_client_auth_response["Auth Response<br/>response model<br/>[AuthResponse.ts]"]
end

subgraph group_server["Server"]
  node_server_entry(("Server Entry<br/>Node bootstrap<br/>[index.js]"))
  node_server_routes["Routes<br/>router<br/>[index.js]"]
  node_server_controller["User Controller<br/>HTTP controller<br/>[user-controller.js]"]
  node_server_user_service["User Service<br/>auth workflow<br/>[user-service.js]"]
  node_server_token_service["Token Service<br/>jwt service<br/>[token-service.js]"]
  node_server_mail_service["Mail Service<br/>notification service<br/>[mail-service.js]"]
  node_server_user_model[("User Model<br/>persistence model<br/>[user-model.js]")]
  node_server_token_model[("Token Model<br/>persistence model<br/>[token-model.js]")]
  node_server_user_dto["User DTO<br/>transfer object<br/>[user-dto.js]"]
  node_server_auth_middleware{{"Auth Middleware<br/>route guard<br/>[auth-middleware.js]"}}
  node_server_error_middleware{{"Error Middleware<br/>error handler"}}
end

node_client_index -->|"renders"| node_client_app
node_client_app -->|"shows"| node_client_login_form
node_client_app -->|"shows"| node_client_activate_form
node_client_app -->|"reads/writes"| node_client_user_store
node_client_login_form -->|"calls"| node_client_auth_service
node_client_activate_form -->|"calls"| node_client_auth_service
node_client_auth_service -->|"uses"| node_client_http
node_client_user_service -->|"uses"| node_client_http
node_client_auth_service -->|"returns"| node_client_auth_response
node_client_user_service -->|"uses"| node_client_user_model
node_client_auth_response -->|"contains"| node_client_user_model
node_server_entry -->|"mounts"| node_server_routes
node_server_routes -->|"dispatches to"| node_server_controller
node_server_controller -->|"delegates"| node_server_user_service
node_server_user_service -->|"creates/verifies"| node_server_token_service
node_server_user_service -->|"sends"| node_server_mail_service
node_server_user_service -->|"persists"| node_server_user_model
node_server_user_service -->|"persists"| node_server_token_model
node_server_user_service -->|"shapes"| node_server_user_dto
node_server_routes -->|"guards"| node_server_auth_middleware
node_server_controller -->|"errors to"| node_server_error_middleware
node_server_user_service -.->|"raises"| node_server_error_middleware
node_client_http -->|"calls API"| node_server_routes
node_server_controller -->|"returns"| node_server_user_dto

click node_client_index "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/index.tsx"
click node_client_app "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/App.tsx"
click node_client_login_form "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/components/LoginForm.tsx"
click node_client_activate_form "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/components/ActivateForm.tsx"
click node_client_user_store "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/store/UserStore.ts"
click node_client_http "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/http/index.ts"
click node_client_auth_service "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/services/AuthService.ts"
click node_client_user_service "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/services/UserService.ts"
click node_client_user_model "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/models/IUser.ts"
click node_client_auth_response "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/models/response/AuthResponse.ts"
click node_server_entry "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/index.js"
click node_server_routes "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/routes/index.js"
click node_server_controller "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/controllers/user-controller.js"
click node_server_user_service "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/user-service.js"
click node_server_token_service "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/token-service.js"
click node_server_mail_service "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/mail-service.js"
click node_server_user_model "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/models/user-model.js"
click node_server_token_model "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/models/token-model.js"
click node_server_user_dto "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/dtos/user-dto.js"
click node_server_auth_middleware "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/middlewares/auth-middleware.js"
click node_server_error_middleware "https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/middlewares/error-middleware.js"

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_client_index,node_client_app,node_client_login_form,node_client_activate_form,node_client_user_store,node_client_http,node_client_auth_service,node_client_user_service,node_client_user_model,node_client_auth_response toneBlue
class node_server_entry,node_server_routes,node_server_controller,node_server_user_service,node_server_token_service,node_server_mail_service,node_server_user_model,node_server_token_model,node_server_user_dto,node_server_auth_middleware,node_server_error_middleware toneAmber
```

## Components

### Client

React + TypeScript SPA for login and activation

- [Entry](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/index.tsx): React bootstrap · Client application bootstrap and render entrypoint · `client/src/index.tsx`
- [App](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/App.tsx): SPA shell · Top-level client component and flow container · `client/src/App.tsx`
- [Login Form](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/components/LoginForm.tsx): auth UI · Login screen for credential-based sign-in · `client/src/components/LoginForm.tsx`
- [Activate Form](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/components/ActivateForm.tsx): activation UI · Account activation form and follow-up flow · `client/src/components/ActivateForm.tsx`
- [User Store](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/store/UserStore.ts): auth state · Frontend auth state and user session boundary · `client/src/store/UserStore.ts`
- [HTTP Client](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/http/index.ts): api client · Shared HTTP boundary for server communication · `client/src/http/index.ts`
- [Auth Service](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/services/AuthService.ts): auth api · Client-side authentication request wrapper · `client/src/services/AuthService.ts`
- [User Service](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/services/UserService.ts): user api · Client-side user/profile request wrapper · `client/src/services/UserService.ts`
- [User Model](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/models/IUser.ts): domain model · Frontend user data contract · `client/src/models/IUser.ts`
- [Auth Response](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/client/src/models/response/AuthResponse.ts): response model · Frontend response contract for auth results · `client/src/models/response/AuthResponse.ts`

### Server

Node.js JWT auth API

- [Server Entry](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/index.js): Node bootstrap · Backend process startup and server initialization · `server/index.js`
- [Routes](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/routes/index.js): router · Main API router and endpoint mounting · `server/routes/index.js`
- [User Controller](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/controllers/user-controller.js): HTTP controller · Express-facing request and response translation layer · `server/controllers/user-controller.js`
- [User Service](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/user-service.js): auth workflow · Core user registration, login, and activation logic · `server/service/user-service.js`
- [Token Service](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/token-service.js): jwt service · JWT creation, validation, and token lifecycle handling · `server/service/token-service.js`
- [Mail Service](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/service/mail-service.js): notification service · Outbound activation email delivery · `server/service/mail-service.js`
- [User Model](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/models/user-model.js): persistence model · Stored user entity boundary · `server/models/user-model.js`
- [Token Model](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/models/token-model.js): persistence model · Stored token entity boundary · `server/models/token-model.js`
- [User DTO](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/dtos/user-dto.js): transfer object · Shaped user payload for API boundaries · `server/dtos/user-dto.js`
- [Auth Middleware](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/middlewares/auth-middleware.js): route guard · Protects routes by validating authentication state · `server/middlewares/auth-middleware.js`
- [Error Middleware](https://github.com/flatwhite-dev/jwtauth-template-/blob/main/server/middlewares/error-middleware.js): error handler · Centralized error normalization and HTTP formatting · `server/middlewares/error-middleware.js`

## Connections

- Entry → App: renders · Bootstraps the SPA root
- App → Login Form: shows · Main login flow UI
- App → Activate Form: shows · Activation flow UI
- App → User Store: reads/writes · Uses auth state to drive UI
- Login Form → Auth Service: calls · Submits login and auth actions
- Activate Form → Auth Service: calls · Submits activation-related requests
- Auth Service → HTTP Client: uses · Sends requests through shared HTTP client
- User Service → HTTP Client: uses · Sends user/profile requests through shared HTTP client
- Auth Service → Auth Response: returns · Consumes auth response shape
- User Service → User Model: uses · Shares user data contract
- Auth Response → User Model: contains · Auth response carries user data
- Server Entry → Routes: mounts · Starts the API router
- Routes → User Controller: dispatches to · Routes request handlers to controller actions
- User Controller → User Service: delegates · Moves business logic out of HTTP layer
- User Service → Token Service: creates/verifies · Central JWT token workflow
- User Service → Mail Service: sends · Triggers activation mail delivery
- User Service → User Model: persists · Reads and updates user records
- User Service → Token Model: persists · Stores token records separately
- User Service → User DTO: shapes · Formats user data for API responses
- Routes → Auth Middleware: guards · Protects authenticated endpoints
- User Controller → Error Middleware: errors to · Normalizes failures into API responses
- User Service → Error Middleware: raises · Domain errors are surfaced for handling
- HTTP Client → Routes: calls API · Frontend communicates with backend endpoints
- User Controller → User DTO: returns · API responses use DTO-shaped user data
