How flatwhite-dev/jwtauth-template- works
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: user-service.js User Service · App.tsx App · user-controller.js User Controller · AuthService.ts Auth Service
Components 21
Client
React + TypeScript SPA for login and activation
- Entry · Client application bootstrap and render entrypoint
client/src/index.tsx - App · Top-level client component and flow container
client/src/App.tsx - Login Form · Login screen for credential-based sign-in
client/src/components/LoginForm.tsx - Activate Form · Account activation form and follow-up flow
client/src/components/ActivateForm.tsx - User Store · Frontend auth state and user session boundary
client/src/store/UserStore.ts - HTTP Client · Shared HTTP boundary for server communication
client/src/http/index.ts - Auth Service · Client-side authentication request wrapper
client/src/services/AuthService.ts - User Service · Client-side user/profile request wrapper
client/src/services/UserService.ts - User Model · Frontend user data contract
client/src/models/IUser.ts - Auth Response · Frontend response contract for auth results
client/src/models/response/AuthResponse.ts
Server
Node.js JWT auth API
- Server Entry · Backend process startup and server initialization
server/index.js - Routes · Main API router and endpoint mounting
server/routes/index.js - User Controller · Express-facing request and response translation layer
server/controllers/user-controller.js - User Service · Core user registration, login, and activation logic
server/service/user-service.js - Token Service · JWT creation, validation, and token lifecycle handling
server/service/token-service.js - Mail Service · Outbound activation email delivery
server/service/mail-service.js - User Model · Stored user entity boundary
server/models/user-model.js - Token Model · Stored token entity boundary
server/models/token-model.js - User DTO · Shaped user payload for API boundaries
server/dtos/user-dto.js - Auth Middleware · Protects routes by validating authentication state
server/middlewares/auth-middleware.js - Error Middleware · Centralized error normalization and HTTP formatting
server/middlewares/error-middleware.js
Connections 24
- 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