# wahyupr/adonis-api-auth architecture

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

- Interactive diagram: https://gitdiagram.com/wahyupr/adonis-api-auth
- Repository: https://github.com/wahyupr/adonis-api-auth

## Overview

##### Main Components
- API Server Core: Represented by the entry files (server.js, start/app.js, start/kernel.js, start/routes.js), which boot up the HTTP server, handle routing, and manage the request lifecycle.
- Controllers: Found under app/Controllers (e.g., AuthController.js, SsoController.js). These handle the HTTP layer and process incoming API requests.
- Middleware: Located in app/Middleware (e.g., Auth.js, Session.js, SecurityHeaders.js) that intercept and process requests/responses for authentication, session management, and security.
- Services: Under app/Services (e.g., AuthService.js, SsoService.js) that encapsulate business logic and processes.
- Models & ORM: Found in app/Models (e.g., User.js, Role.js). These work together with Lucid ORM for database interactions. Their filters and traits further encapsulate query logic.
- Validators: Under app/Validators, which enforce business rules on payload data before processing.
- Configuration & Environment: Files under config and .env files for environment-specific settings (database, auth, cache, session etc.).
- Database and Migrations: The database folder includes migrations, factories, and seeds that show how the database schema is managed.
- Certificates: The cert directory indicates the security configurations used for JWT authentication (RSA keys).
- Documentation: The public/docs folder contains API documentation (likely a Swagger UI setup) to access the API documentation via a browser.

##### Relationships and Interactions
- The entry point (server.js) initializes the application and triggers the routing defined in start/routes.js. Routes are connected to controllers in app/Controllers.
- Once a request is routed, middleware (from app/Middleware) is executed to handle authentication, sessions, and any required security enhancements.
- Controllers then invoke corresponding services (under app/Services) which encapsulate core business logic.
- Services interact with models (app/Models) via Lucid ORM for data storage, retrieval, or modification.
- Validators (app/Validators) are used to verify incoming data, ensuring the correctness before any business logic is executed.
- The configuration files in config directory and environment setup (via .env files) help manage settings across the application. Migration and seed scripts (in database folder) define the database schema.
- The certificate files are used in secure communications or token generation, mainly impacting authentication.

##### Architectural Patterns & Design Principles
- MVC-like Structure: Controllers, Models, and Services are clearly separated, reflecting a standard pattern for API design.
- Middleware Pipeline: Shows clear layering for request processing and security.
- Separation of Concerns: Business logic in services, validation in separate modules, and database interactions in models.
- Configuration-Driven Design: Uses environment-specific configuration and centralized config files.
- Documentation Integration: Includes a Swagger-based documentation component which is automatically updated via the public/docs folder.

##### Technologies & Frameworks
- AdonisJs: The main framework for structuring the application.
- Lucid ORM: Used for database interactions.
- Node.js & NPM: As indicated by package.json and version recommendations.
- JWT (using RSA keys): Security certificates in the cert folder for token-based authentication.
- Swagger UI: For API documentation (see files in public/docs).

##### Instructing the Principal Software Engineer
- External dependencies (e.g., the node environment, external clients interacting with the API, and the usage of JWT for authentication) clearly.
- Notes on the project’s scalability and middleware extensibility patterns if necessary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("HTTP Client"):::client

    subgraph "API Server Core"
        A1("Server.js"):::core
        A2("App.js"):::core
        A3("Kernel.js"):::core
        A4("Routes.js"):::core
    end

    subgraph "Middleware Layer"
        M1("Auth Middleware"):::middleware
        M2("ConvertEmptyStringsToNull"):::middleware
        M3("Security Headers"):::middleware
        M4("Session Middleware"):::middleware
    end

    subgraph "Controller Layer"
        C1("Auth Controller"):::controller
        C2("SSO Controller"):::controller
    end

    subgraph "Validators"
        V1("Validators"):::validator
    end

    subgraph "Services / Business Logic"
        S1("Auth Service"):::service
        S2("SSO Service"):::service
    end

    subgraph "Data & Persistence"
        D1("User Model"):::model
        D2("Role Model"):::model
        D3("RoleUser Model"):::model
        D4("Session Model"):::model
        D5("SsoAccess Model"):::model
        D6("Token Model"):::model
        D7("Model Traits"):::model
    end

    subgraph "Database & Migrations"
        DB("Database, Migrations & Seeds"):::database
    end

    subgraph "Configuration & Environment"
        CF("Configuration Files"):::config
        ED("Environment Settings"):::config
    end

    subgraph "Security"
        CERT("Certificates"):::cert
    end

    subgraph "Documentation"
        DOC("API Documentation"):::docs
    end

    %% Flow Connections
    Client --> A1
    A4 --> M1
    M1 --> C1
    C1 --> V1
    C2 --> V1
    V1 --> S1
    V1 --> S2
    S1 --> D1
    S2 --> D5
    D1 --> DB
    D2 --> DB
    D3 --> DB
    D4 --> DB
    D5 --> DB
    D6 --> DB
    D7 --> DB

    %% Additional Connections for Cross-cutting Concerns
    CF --- A1
    ED --- A1
    CERT --- M1
    Client --- DOC

    %% Click Events for API Server Core
    click A1 "https://github.com/wahyupr/adonis-api-auth/blob/main/server.js"
    click A2 "https://github.com/wahyupr/adonis-api-auth/blob/main/start/app.js"
    click A3 "https://github.com/wahyupr/adonis-api-auth/blob/main/start/kernel.js"
    click A4 "https://github.com/wahyupr/adonis-api-auth/blob/main/start/routes.js"

    %% Click Events for Controllers
    click C1 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Controllers/Http/AuthController.js"
    click C2 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Controllers/Http/SsoController.js"

    %% Click Events for Middleware
    click M1 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Middleware/Auth.js"
    click M2 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Middleware/ConvertEmptyStringsToNull.js"
    click M3 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Middleware/SecurityHeaders.js"
    click M4 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Middleware/Session.js"

    %% Click Events for Services
    click S1 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Services/AuthService.js"
    click S2 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Services/SsoService.js"

    %% Click Events for Models
    click D1 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/User.js"
    click D2 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/Role.js"
    click D3 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/RoleUser.js"
    click D4 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/Session.js"
    click D5 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/SsoAccess.js"
    click D6 "https://github.com/wahyupr/adonis-api-auth/blob/main/app/Models/Token.js"
    click D7 "https://github.com/wahyupr/adonis-api-auth/tree/main/app/Models/Traits"

    %% Click Events for Configuration & Environment
    click CF "https://github.com/wahyupr/adonis-api-auth/tree/main/config"
    click ED "https://github.com/wahyupr/adonis-api-auth/blob/main/.env.dump"

    %% Click Event for Database
    click DB "https://github.com/wahyupr/adonis-api-auth/tree/main/database"

    %% Click Event for Certificates
    click CERT "https://github.com/wahyupr/adonis-api-auth/tree/main/cert"

    %% Click Event for Documentation
    click DOC "https://github.com/wahyupr/adonis-api-auth/tree/main/public/docs"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef middleware fill:#cff,stroke:#333,stroke-width:2px;
    classDef controller fill:#fcf,stroke:#333,stroke-width:2px;
    classDef validator fill:#ff9,stroke:#333,stroke-width:2px;
    classDef service fill:#9f9,stroke:#333,stroke-width:2px;
    classDef model fill:#ffb,stroke:#333,stroke-width:2px;
    classDef database fill:#f99,stroke:#333,stroke-width:2px;
    classDef config fill:#ddd,stroke:#333,stroke-width:2px;
    classDef cert fill:#dda,stroke:#333,stroke-width:2px;
    classDef docs fill:#add,stroke:#333,stroke-width:2px;
```
