How abhadimishra/funds24_backend works
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: app.ts App · auth.service.ts Auth Service · auth.controller.ts Auth Ctrl · auth.middleware.ts Auth Guard
Components 26
Runtime
Process entrypoint and application assembly
HTTP API
Routing, controllers, and middleware boundary
- Routes · Top-level route registration
backend/src/routes/index.ts - Auth Routes · Auth endpoint definitions
backend/src/routes/auth.routes.ts - Auth Ctrl · HTTP request/response handling for auth
backend/src/controllers/auth.controller.ts - Request Log · Per-request logging and tracing
backend/src/middlewares/request-logger.middleware.ts - Rate Limit · Abuse protection for inbound requests
backend/src/middlewares/rate-limit.middleware.ts - Auth Guard · Protects authenticated endpoints
backend/src/middlewares/auth.middleware.ts - Validate · Input and schema enforcement
backend/src/middlewares/validate.middleware.ts - Error Handler · Centralized error translation
backend/src/middlewares/error.middleware.ts
Auth Domain
Authentication workflow and supporting domain logic
- Auth Service · Main authentication workflow
backend/src/services/auth.service.ts - Token Service · Token creation and verification
backend/src/services/token.service.ts - Mail Service · Outbound email delivery
backend/src/services/mail.service.ts
Persistence
Models and database connection
- User · User persistence model
backend/src/models/user.model.ts - Session · Auth session persistence model
backend/src/models/auth-session.model.ts - Challenge · Login challenge persistence model
backend/src/models/login-challenge.model.ts - Database · Database connection boundary
backend/src/config/database.ts
Support
Shared utilities, validation, and types
- Env Config · Runtime configuration from environment
backend/src/config/env.ts - Auth Validator · Auth request validation rules
backend/src/validators/auth.validator.ts - Security Utils · Shared security primitives
backend/src/utils/security.ts - App Error · Application error shape
backend/src/utils/app-error.ts - API Response · Standard success response format
backend/src/utils/api-response.ts - Async Handler · Async route wrapper for error propagation
backend/src/utils/async-handler.ts - Logger · Application logging
backend/src/utils/logger.ts - Express Types · Extends request context for auth state
backend/src/types/express/index.d.ts
Connections 30
- 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