# abhadimishra/funds24_backend architecture

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

- Interactive diagram: https://gitdiagram.com/abhadimishra/funds24_backend
- Repository: https://github.com/abhadimishra/funds24_backend

## Overview

This repository is a TypeScript Node.js backend for the Funds24 API, organized as a layered HTTP service with a strong focus on authentication flows.

1. Runtime and bootstrap
- `backend/src/server.ts` is the process entrypoint.
- `backend/src/app.ts` assembles the Express application, middleware stack, and route registration.
- Environment configuration is centralized in `config/env.ts`, so runtime behavior is driven by `.env` values rather than hardcoded settings.

2. HTTP boundary
- The API surface is routed through `routes/index.ts`, with auth-specific endpoints in `routes/auth.routes.ts`.
- Controllers sit directly behind the routes and translate HTTP requests/responses into service calls.
- `controllers/auth.controller.ts` is the main request handler layer visible in the tree.

3. Request lifecycle
- Requests pass through middleware before reaching controllers.
- The middleware set includes:
  - `request-logger.middleware.ts` for observability
  - `rate-limit.middleware.ts` for abuse protection
  - `auth.middleware.ts` for protected endpoints
  - `validate.middleware.ts` for schema/input enforcement
  - `error.middleware.ts` for centralized error handling
- This creates a clear boundary between transport concerns and business logic.

4. Domain/service layer
- `services/auth.service.ts` contains the core authentication workflow.
- Supporting services split adjacent responsibilities:
  - `token.service.ts` for token creation/verification and auth state handling
  - `mail.service.ts` for outbound email delivery
- The service layer is where the main business rules live, keeping controllers thin.

5. Persistence and domain models
- The repository includes three models:
  - `user.model.ts`
  - `auth-session.model.ts`
  - `login-challenge.model.ts`
- These imply a persistence-backed auth system with user records, session tracking, and some form of challenge/verification step.
- `config/database.ts` is the database connection boundary; the exact storage engine is not shown in the tree.

6. Authentication flow shape
- The presence of `login-challenge` and `auth-session` suggests a multi-step login model rather than a single password-only flow.
- Typical data flow is likely: request → validation → auth controller → auth service → token/session/challenge persistence → optional email dispatch → HTTP response.
- Protected requests then reverse that path through token/session validation in middleware.

7. Validation and security
- Input validation is isolated under `validators/auth.validator.ts`.
- Security-related helpers live in `utils/security.ts`, indicating shared primitives such as hashing, token utilities, or secure comparisons.
- `constants/auth.ts` centralizes auth-related constants to avoid scattered magic values.

8. Error handling and response shaping
- `utils/app-error.ts` and `middlewares/error.middleware.ts` define the application error contract.
- `utils/api-response.ts` standardizes successful responses.
- `utils/async-handler.ts` reduces boilerplate around async route handlers and error propagation.

9. Logging and observability
- `utils/logger.ts` and the request logger middleware provide application-level and request-level visibility.
- This is important for tracing auth attempts, rate limiting, and failure modes across the request pipeline.

10. Type and framework extensions
- `types/express/index.d.ts` extends Express request types, likely to attach authenticated user/session context.
- This keeps auth state available across middleware, controllers, and services without passing it manually.

11. External dependencies and infrastructure impact
- The only clearly implied external integrations are the database and an email system.
- Mail delivery is abstracted behind `mail.service.ts`, which keeps transport details out of auth logic and makes the service easier to swap or mock.

12. Testing and tooling
- The project uses Vitest (`vitest.config.ts`), indicating unit/integration testing support in the backend codebase.
- TypeScript configs are split for normal and test builds, which suggests a compiled or transpiled Node backend rather than a dynamically executed one.

Overall, the architecture is a conventional backend service stack: Express at the edge, middleware for cross-cutting concerns, controllers for HTTP translation, services for business logic, and models/database access for persistence. The auth subsystem is the dominant domain in the repository.

Main entry points: [`backend/src/app.ts`](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/app.ts) (App), [`backend/src/services/auth.service.ts`](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/auth.service.ts) (Auth Service), [`backend/src/controllers/auth.controller.ts`](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/controllers/auth.controller.ts) (Auth Ctrl), [`backend/src/middlewares/auth.middleware.ts`](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/auth.middleware.ts) (Auth Guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server(("Server<br/>entrypoint<br/>[server.ts]"))
  node_app["App<br/>[app.ts]"]
end

subgraph group_http["HTTP API"]
  node_router_index["Routes<br/>route index<br/>[index.ts]"]
  node_auth_routes["Auth Routes<br/>route module<br/>[auth.routes.ts]"]
  node_auth_controller["Auth Ctrl<br/>controller<br/>[auth.controller.ts]"]
  node_request_logger["Request Log<br/>middleware"]
  node_rate_limit["Rate Limit<br/>middleware"]
  node_auth_mw["Auth Guard<br/>middleware<br/>[auth.middleware.ts]"]
  node_validate_mw["Validate<br/>middleware"]
  node_error_mw["Error Handler<br/>middleware"]
end

subgraph group_auth["Auth Domain"]
  node_auth_service["Auth Service<br/>[auth.service.ts]"]
  node_token_service["Token Service<br/>[token.service.ts]"]
  node_mail_service["Mail Service<br/>[mail.service.ts]"]
end

subgraph group_data["Persistence"]
  node_user_model[("User<br/>model<br/>[user.model.ts]")]
  node_session_model[("Session<br/>model")]
  node_challenge_model[("Challenge<br/>model")]
  node_database[("Database<br/>connection<br/>[database.ts]")]
end

subgraph group_support["Support"]
  node_env["Env Config<br/>[env.ts]"]
  node_auth_validator["Auth Validator<br/>[auth.validator.ts]"]
  node_security["Security Utils<br/>[security.ts]"]
  node_app_error["App Error<br/>error contract<br/>[app-error.ts]"]
  node_api_response["API Response<br/>response helper<br/>[api-response.ts]"]
  node_async_handler["Async Handler<br/>[async-handler.ts]"]
  node_logger["Logger<br/>[logger.ts]"]
  node_express_types["Express Types<br/>type augmentation<br/>[index.d.ts]"]
end

subgraph group_tooling["Tooling"]
  node_vitest["Vitest<br/>test config<br/>[vitest.config.ts]"]
end

node_server -->|"boots"| node_app
node_app -->|"reads"| node_env
node_app -->|"uses"| node_request_logger
node_app -->|"uses"| node_rate_limit
node_app -->|"uses"| node_auth_mw
node_app -->|"uses"| node_validate_mw
node_app -->|"uses"| node_error_mw
node_app -->|"routes"| node_router_index
node_router_index -->|"mounts"| node_auth_routes
node_auth_routes -->|"validates"| node_auth_validator
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"wraps"| node_async_handler
node_auth_controller -->|"calls"| node_auth_service
node_auth_controller -->|"formats"| node_api_response
node_auth_service -->|"uses"| node_token_service
node_auth_service -->|"uses"| node_mail_service
node_auth_service -->|"persists"| node_user_model
node_auth_service -->|"persists"| node_session_model
node_auth_service -->|"persists"| node_challenge_model
node_auth_service -->|"uses"| node_security
node_auth_service -->|"throws"| node_app_error
node_auth_service -->|"stores"| node_database
node_auth_mw -->|"verifies"| node_token_service
node_auth_mw -->|"checks"| node_session_model
node_validate_mw -->|"reports"| node_app_error
node_error_mw -->|"handles"| node_app_error
node_app -->|"logs"| node_logger
node_auth_controller -->|"augments"| node_express_types
node_auth_mw -->|"augments"| node_express_types
node_vitest -.->|"tests"| node_app

click node_server "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/server.ts"
click node_app "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/app.ts"
click node_router_index "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/routes/index.ts"
click node_auth_routes "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/routes/auth.routes.ts"
click node_auth_controller "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/controllers/auth.controller.ts"
click node_request_logger "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/request-logger.middleware.ts"
click node_rate_limit "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/rate-limit.middleware.ts"
click node_auth_mw "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/auth.middleware.ts"
click node_validate_mw "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/validate.middleware.ts"
click node_error_mw "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/error.middleware.ts"
click node_auth_service "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/auth.service.ts"
click node_token_service "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/token.service.ts"
click node_mail_service "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/mail.service.ts"
click node_user_model "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/user.model.ts"
click node_session_model "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/auth-session.model.ts"
click node_challenge_model "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/login-challenge.model.ts"
click node_database "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/config/database.ts"
click node_env "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/config/env.ts"
click node_auth_validator "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/validators/auth.validator.ts"
click node_security "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/security.ts"
click node_app_error "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/app-error.ts"
click node_api_response "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/api-response.ts"
click node_async_handler "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/async-handler.ts"
click node_logger "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/logger.ts"
click node_express_types "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/types/express/index.d.ts"
click node_vitest "https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/vitest.config.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_server,node_app toneBlue
class node_router_index,node_auth_routes,node_auth_controller,node_request_logger,node_rate_limit,node_auth_mw,node_validate_mw,node_error_mw toneAmber
class node_auth_service,node_token_service,node_mail_service toneMint
class node_user_model,node_session_model,node_challenge_model,node_database toneRose
class node_env,node_auth_validator,node_security,node_app_error,node_api_response,node_async_handler,node_logger,node_express_types toneIndigo
class node_vitest toneTeal
```

## Components

### Runtime

Process entrypoint and application assembly

- [Server](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/server.ts): entrypoint · Starts the Node process and boots the app · `backend/src/server.ts`
- [App](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/app.ts): express app · Assembles middleware and registers routes · `backend/src/app.ts`

### HTTP API

Routing, controllers, and middleware boundary

- [Routes](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/routes/index.ts): route index · Top-level route registration · `backend/src/routes/index.ts`
- [Auth Routes](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/routes/auth.routes.ts): route module · Auth endpoint definitions · `backend/src/routes/auth.routes.ts`
- [Auth Ctrl](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/controllers/auth.controller.ts): controller · HTTP request/response handling for auth · `backend/src/controllers/auth.controller.ts`
- [Request Log](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/request-logger.middleware.ts): middleware · Per-request logging and tracing · `backend/src/middlewares/request-logger.middleware.ts`
- [Rate Limit](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/rate-limit.middleware.ts): middleware · Abuse protection for inbound requests · `backend/src/middlewares/rate-limit.middleware.ts`
- [Auth Guard](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/auth.middleware.ts): middleware · Protects authenticated endpoints · `backend/src/middlewares/auth.middleware.ts`
- [Validate](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/validate.middleware.ts): middleware · Input and schema enforcement · `backend/src/middlewares/validate.middleware.ts`
- [Error Handler](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/middlewares/error.middleware.ts): middleware · Centralized error translation · `backend/src/middlewares/error.middleware.ts`

### Auth Domain

Authentication workflow and supporting domain logic

- [Auth Service](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/auth.service.ts): service · Main authentication workflow · `backend/src/services/auth.service.ts`
- [Token Service](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/token.service.ts): service · Token creation and verification · `backend/src/services/token.service.ts`
- [Mail Service](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/services/mail.service.ts): service · Outbound email delivery · `backend/src/services/mail.service.ts`

### Persistence

Models and database connection

- [User](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/user.model.ts): model · User persistence model · `backend/src/models/user.model.ts`
- [Session](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/auth-session.model.ts): model · Auth session persistence model · `backend/src/models/auth-session.model.ts`
- [Challenge](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/models/login-challenge.model.ts): model · Login challenge persistence model · `backend/src/models/login-challenge.model.ts`
- [Database](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/config/database.ts): connection · Database connection boundary · `backend/src/config/database.ts`

### Support

Shared utilities, validation, and types

- [Env Config](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/config/env.ts): config · Runtime configuration from environment · `backend/src/config/env.ts`
- [Auth Validator](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/validators/auth.validator.ts): validator · Auth request validation rules · `backend/src/validators/auth.validator.ts`
- [Security Utils](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/security.ts): utility · Shared security primitives · `backend/src/utils/security.ts`
- [App Error](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/app-error.ts): error contract · Application error shape · `backend/src/utils/app-error.ts`
- [API Response](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/api-response.ts): response helper · Standard success response format · `backend/src/utils/api-response.ts`
- [Async Handler](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/async-handler.ts): utility · Async route wrapper for error propagation · `backend/src/utils/async-handler.ts`
- [Logger](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/utils/logger.ts): utility · Application logging · `backend/src/utils/logger.ts`
- [Express Types](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/types/express/index.d.ts): type augmentation · Extends request context for auth state · `backend/src/types/express/index.d.ts`

### Tooling

Build and test configuration

- [Vitest](https://github.com/abhadimishra/funds24_backend/blob/main/backend/src/vitest.config.ts): test config · Test runner configuration · `backend/src/vitest.config.ts`

## Connections

- Server → App: boots · Process entrypoint initializes the application
- App → Env Config: reads · Application behavior is driven by environment config
- App → Request Log: uses · Installs request logging middleware
- App → Rate Limit: uses · Installs request throttling middleware
- App → Auth Guard: uses · Installs auth protection middleware
- App → Validate: uses · Installs request validation middleware
- App → Error Handler: uses · Installs centralized error handling
- App → Routes: routes · Registers the API route tree
- Routes → Auth Routes: mounts · Delegates auth endpoints to the auth router
- Auth Routes → Auth Validator: validates · Applies auth-specific input rules
- Auth Routes → Auth Ctrl: dispatches · Routes hand off to controller handlers
- Auth Ctrl → Async Handler: wraps · Handlers are wrapped for async error flow
- Auth Ctrl → Auth Service: calls · Controller delegates business logic to service layer
- Auth Ctrl → API Response: formats · Controller emits standard response shapes
- Auth Service → Token Service: uses · Auth workflow depends on token/session operations
- Auth Service → Mail Service: uses · Auth workflow can trigger email delivery
- Auth Service → User: persists · Uses user records during authentication
- Auth Service → Session: persists · Tracks active auth sessions
- Auth Service → Challenge: persists · Handles login challenge records
- Auth Service → Security Utils: uses · Relies on shared security primitives
- Auth Service → App Error: throws · Signals domain and workflow failures
- Auth Service → Database: stores · Persists auth state through the database boundary
- Auth Guard → Token Service: verifies · Protected requests validate auth state via tokens
- Auth Guard → Session: checks · Middleware may consult session state
- Validate → App Error: reports · Validation failures are converted into app errors
- Error Handler → App Error: handles · Central error middleware consumes app errors
- App → Logger: logs · App-level logging support
- Auth Ctrl → Express Types: augments · Controllers rely on extended request context
- Auth Guard → Express Types: augments · Authenticated context is attached to requests
- Vitest → App: tests · Test config targets the backend app