# johnrellis/secure-api architecture

> Architecture diagram of the GitHub repository johnrellis/secure-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnrellis/secure-api
- Repository: https://github.com/johnrellis/secure-api

## Overview

##### Main components of the system
- Entry Point & Server: The app (app.mjs) which likely bootstraps the Express (or similar) server.
- API Versioning & Routing: The “routes/v1” directory indicates that the API is versioned and organized by RESTful routes. There are dedicated routers (e.g., auth-router, token-router, user-router) that manage the API endpoints.
- Controllers: Located in “routes/v1/controllers”, these are responsible for handling API business logic for different endpoints (auth, token, user).
- Domain Models: In “routes/v1/domain”, you have definitions for entities (for example, a User model).
- Middleware: Under “routes/v1/middleware”, particularly the JWT middleware, which secures the endpoints by verifying the token from the request.
- Services: In “routes/v1/services”, these modules abstract the business operations, including token management and user-related functionality.
- Storage: The “routes/v1/storage” directory handles data persistence and interactions for user data.
- Additional Scripts: The “scripts” directory includes utilities for creating tokens, password hashing, and jwt verification—useful for both development and security management.

##### Relationships and Interactions
- Client Requests → Server (via app.mjs).
- The server directs the request to the appropriate v1 router based on URL patterns.
- In the routing layer, incoming requests pass through middleware (e.g., JWT check) before reaching the controllers.
- Controllers act as an intermediary, handing off tasks to services.
- Services perform domain-specific operations and interact with storage (which in turn handles domain data/models).
- For token-related actions, the token service and associated scripts create and validate tokens, with JWT middleware ensuring secure access.

##### Architectural Patterns and Design Principles
- Layered architecture: Separation of concerns is evident by dividing responsibilities among routers, controllers, services, domain models, and storage.
- Modularization: API versioning (v1) allows for future iterations without breaking existing functionality.
- Security-centric design: JWT-based authentication is enforced consistently across the routing layer via dedicated middleware.

##### Relevant Technologies/Frameworks
- Node.js with ES module syntax (as noted by the .mjs file extensions).
- Likely use of Express or a similar Node HTTP framework.
- Environment-based configuration illustrated by the external .env file (e.g., JWT_SECRET).

- Clear labeling for each component (e.g., "User Controller", "Token Service").
- Annotations noting that the project follows a layered design which encourages separation of concerns, making it easier to modify, test, and secure each component.

Overall, focus on detailing how each module fits within the security-focused API application and use clear labels and flow directions to prevent any ambiguity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Level 1: Client
    Client("Client Request"):::client

    %% Level 2: Server Entry
    Server("Server - app.mjs"):::server

    %% Level 3: API Routers (three branches)
    AuthRouter("Auth Router"):::router
    TokenRouter("Token Router"):::router
    UserRouter("User Router"):::router

    %% Level 4: JWT Middleware (applied to all routes)
    JWTMiddleware("JWT Middleware"):::middleware

    %% Level 5: Controllers 
    AuthController("Auth Controller"):::controller
    TokenController("Token Controller"):::controller
    UserController("User Controller"):::controller

    %% Level 6: Services (only Token and User have dedicated services)
    TokenService("Token Service"):::service
    UserService("User Service"):::service

    %% Level 7: Data Persistence & Domain
    UserStorage("User Storage"):::storage
    UserModel("User Model"):::domain

    %% Level 8: Utility Scripts (for token management and security)
    CreateJWT("create-jwt.mjs"):::utility
    HashPasswords("hash-passwords.mjs"):::utility
    VerifyJWT("verify-jwt.mjs"):::utility

    %% Connections for Auth Branch
    Client -->|"sends request"| Server
    Server -->|"routes to"| AuthRouter
    AuthRouter -->|"passes through"| JWTMiddleware
    JWTMiddleware -->|"invokes"| AuthController

    %% Connections for Token Branch
    Server -->|"routes to"| TokenRouter
    TokenRouter -->|"passes through"| JWTMiddleware
    JWTMiddleware -->|"invokes"| TokenController
    TokenController -->|"calls"| TokenService

    %% Connections for User Branch
    Server -->|"routes to"| UserRouter
    UserRouter -->|"passes through"| JWTMiddleware
    JWTMiddleware -->|"invokes"| UserController
    UserController -->|"calls"| UserService

    %% Common Data Persistence Flow (for Token and User services)
    TokenService -->|"persists data"| UserStorage
    UserService -->|"persists data"| UserStorage
    UserStorage -->|"manages"| UserModel

    %% Utility Scripts usage by Token Service
    TokenService -->|"uses"| CreateJWT
    TokenService -->|"uses"| HashPasswords
    TokenService -->|"uses"| VerifyJWT

    %% Click Events
    click Server "https://github.com/johnrellis/secure-api/blob/main/app.mjs"
    click AuthRouter "https://github.com/johnrellis/secure-api/blob/main/routes/v1/auth-router.mjs"
    click TokenRouter "https://github.com/johnrellis/secure-api/blob/main/routes/v1/token-router.mjs"
    click UserRouter "https://github.com/johnrellis/secure-api/blob/main/routes/v1/user-router.mjs"
    click JWTMiddleware "https://github.com/johnrellis/secure-api/blob/main/routes/v1/middleware/jwt.mjs"
    click AuthController "https://github.com/johnrellis/secure-api/blob/main/routes/v1/controllers/auth-controller.mjs"
    click TokenController "https://github.com/johnrellis/secure-api/blob/main/routes/v1/controllers/token-controller.mjs"
    click UserController "https://github.com/johnrellis/secure-api/blob/main/routes/v1/controllers/user-controller.mjs"
    click TokenService "https://github.com/johnrellis/secure-api/blob/main/routes/v1/services/token-service.mjs"
    click UserService "https://github.com/johnrellis/secure-api/blob/main/routes/v1/services/user-service.mjs"
    click UserStorage "https://github.com/johnrellis/secure-api/blob/main/routes/v1/storage/user-storage.mjs"
    click UserModel "https://github.com/johnrellis/secure-api/blob/main/routes/v1/domain/user.mjs"
    click CreateJWT "https://github.com/johnrellis/secure-api/blob/main/scripts/create-jwt.mjs"
    click HashPasswords "https://github.com/johnrellis/secure-api/blob/main/scripts/hash-passwords.mjs"
    click VerifyJWT "https://github.com/johnrellis/secure-api/blob/main/scripts/verify-jwt.mjs"

    %% Styling
    classDef client fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef router fill:#C0FFC0,stroke:#333,stroke-width:2px;
    classDef middleware fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef controller fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef service fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef storage fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef domain fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef utility fill:#E0E0E0,stroke:#333,stroke-width:2px;
```
