# nhan925/_underscore-ex-be architecture

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

- Interactive diagram: https://gitdiagram.com/nhan925/_underscore-ex-be
- Repository: https://github.com/nhan925/_underscore-ex-be

## Overview

##### Main Components
- API Endpoints (Controllers): Include components like AuthController, StudentController, FacultyController, etc. These are the entry points for client requests.
- Business Logic Layer (Services): Represent services such as StudentService, FacultyService, JwtService, etc. This layer handles processing incoming requests and orchestrating the business logic.
- Data Access Layer (Repositories): Show repositories (e.g., StudentRepository, FacultyRepository) which directly interact with the database.
- Contracts: Represent interfaces under the Contracts folder. They ensure that Services and Repositories adhere to specific contracts, enhancing modularity and testability.
- Middleware: Include components such as ExceptionHandlingMiddleware and LoggingEnrichmentMiddleware which are used to intercept HTTP requests and responses, handling exceptions and logging.
- Helpers: Show utilities like JsonbTypeHandler that assist with data processing (i.e., custom Dapper type handling for JSON).
- External Dependencies: Although not part of the code itself, note the integration point with the frontend (as mentioned in the README) and the database creation script (create_db.sql).

##### Relationships and Interactions
- Request flow starting from the external client (or the Frontend as referenced in the README) who sends HTTP requests to the Controllers.
- That Middleware wraps around the API layer to provide cross-cutting concerns such as exception handling and logging.
- That the Contracts layer interacts with both the Services and Repositories ensuring that components depend on abstractions rather than concrete implementations.
- Optionally, add configuration and environment variable management (via .env and appsettings.json files) as supporting elements that impact the configuration and runtime behavior.

##### Architectural Patterns and Design Principles
- Layered (or clean) architecture that clearly delineates responsibilities among the API, Business, and Data layers.
- Use of dependency injection with Interfaces found in the Contracts directory, ensuring easier testing and loose coupling between components.
- Mention that the program leverages middleware to handle cross-cutting concerns.
- Adherence to SOLID principles through the clear interface definitions and separation of concerns.

##### Relevant Technologies, Frameworks, or Libraries
- ASP.NET for the API.
- Dapper could be assumed as a micro-ORM (hinted by the custom JsonbTypeHandler) for database operations.
- Swagger integration is mentioned (for API testing and documentation).
- JWT for authentication (implemented within JwtService).

##### Detailed Capture
- Extra details like JWT authentication flow within the AuthController and JwtService, or how the JSON type handler fits in the context of data mapping.
- Incorporate the indicated call flow from the “Documents/call_flow.svg” as a reference point to visually align with the project’s operational flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        FE("Frontend"):::external
        SW("Swagger"):::external
        CONF("Configuration"):::external
        DS("Database Script"):::external
        DB("Database"):::external
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        EH("ExceptionHandlingMiddleware"):::middleware
        LE("LoggingEnrichmentMiddleware"):::middleware
    end

    %% API Layer (Controllers)
    subgraph "API Layer (Controllers)"
        AC("AuthController"):::controllers
        SC("StudentController"):::controllers
        FC("FacultyController"):::controllers
    end

    %% Business Logic Layer (Services)
    subgraph "Business Layer (Services)"
        SS("StudentService"):::services
        FS("FacultyService"):::services
        JS("JwtService"):::services
    end

    %% Data Access Layer (Repositories)
    subgraph "Data Access Layer (Repositories)"
        SR("StudentRepository"):::repositories
        FR("FacultyRepository"):::repositories
    end

    %% Models and Contracts
    subgraph "Models & Contracts"
        MD("Models"):::models
        CT("Contracts"):::contracts
    end

    %% Helper Utilities
    subgraph "Helper Utilities"
        JT("JsonbTypeHandler"):::helpers
    end

    %% Connections

    %% External Dependencies to Middleware
    FE -->|"HTTPRequest"| EH
    FE -->|"HTTPRequest"| LE

    %% Middleware to Controllers
    EH -->|"handles"| AC
    EH -->|"handles"| SC
    EH -->|"handles"| FC
    LE -->|"logs"| AC
    LE -->|"logs"| SC
    LE -->|"logs"| FC

    %% Controllers to Services
    AC -->|"auth_calls"| JS
    SC -->|"student_calls"| SS
    FC -->|"faculty_calls"| FS

    %% Services to Repositories
    SS -->|"DB_op"| SR
    FS -->|"DB_op"| FR

    %% Repositories to Database
    SR -->|"queries"| DB
    FR -->|"queries"| DB

    %% Services and Repositories implement Contracts
    SS -->|"implements"| CT
    FS -->|"implements"| CT
    JS -->|"implements"| CT
    SR -->|"implements"| CT
    FR -->|"implements"| CT

    %% Configuration links
    CONF -->|"configures"| SS
    CONF -->|"configures"| FR
    CONF -->|"connects"| DB

    %% Swagger documentation
    SW -->|"docs"| AC
    SW -->|"docs"| SC
    SW -->|"docs"| FC

    %% Click Events
    click AC "https://github.com/nhan925/_underscore-ex-be/blob/main/Controllers/AuthController.cs"
    click SC "https://github.com/nhan925/_underscore-ex-be/blob/main/Controllers/StudentController.cs"
    click FC "https://github.com/nhan925/_underscore-ex-be/blob/main/Controllers/FacultyController.cs"
    click SS "https://github.com/nhan925/_underscore-ex-be/blob/main/Services/StudentService.cs"
    click FS "https://github.com/nhan925/_underscore-ex-be/blob/main/Services/FacultyService.cs"
    click JS "https://github.com/nhan925/_underscore-ex-be/blob/main/Services/JwtService.cs"
    click SR "https://github.com/nhan925/_underscore-ex-be/blob/main/Repositories/StudentRepository.cs"
    click FR "https://github.com/nhan925/_underscore-ex-be/blob/main/Repositories/FacultyRepository.cs"
    click MD "https://github.com/nhan925/_underscore-ex-be/tree/main/Models"
    click CT "https://github.com/nhan925/_underscore-ex-be/tree/main/Contracts"
    click EH "https://github.com/nhan925/_underscore-ex-be/blob/main/Middlewares/ExceptionHandlingMiddleware.cs"
    click LE "https://github.com/nhan925/_underscore-ex-be/blob/main/Middlewares/LoggingEnrichmentMiddleware.cs"
    click JT "https://github.com/nhan925/_underscore-ex-be/blob/main/Helpers/JsonbTypeHandler.cs"
    click CONF "https://github.com/nhan925/_underscore-ex-be/blob/main/appsettings.json"
    click DS "https://github.com/nhan925/_underscore-ex-be/blob/main/create_db.sql"

    %% Styles
    classDef controllers fill:#8EC0FF,stroke:#0277BD,stroke-width:2px;
    classDef services fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef repositories fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef models fill:#F0F4C3,stroke:#9E9D24,stroke-width:2px;
    classDef contracts fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef middleware fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
    classDef helpers fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
```
