# oussama-sil/sci_api architecture

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

- Interactive diagram: https://gitdiagram.com/oussama-sil/sci_api
- Repository: https://github.com/oussama-sil/sci_api

## Overview

##### Project Type and Purpose
- Type: Backend REST API (monolithic Node.js/Express service)
- Purpose: Expose endpoints for an Intelligent Mailbox system. It accepts hardware (Arduino) events, manages mailbox and person records, dispatches email notifications via SMTP, and persists data in MySQL.

##### File Structure (Layered Architecture)
Top-level components:
- config/           – configuration (DB credentials, JWT secret)
- index.js          – Express app entry point
- routes/           – HTTP route definitions (API layer)
- services/         – business logic (service layer)
- model/            – data access objects (DAO/ORM layer)
- script_database.sql – database schema script
Auxiliary:
- package.json      – dependencies (Express, MySQL, JWT, nodemailer)
- .gitignore
- Looping1.lo1, .loo – domain-specific files (can be omitted if not relevant)

##### README Insights
- Confirms tech stack: Node.js/Express, MySQL
- Core functionality: Intelligent mailbox API (CRUD for persons/mailboxes, event ingestion, email notifications)

##### Main Components
A. External Clients/Systems
- Arduino device (sends events via HTTP POST)
- Administrator/Client application or CLI (consumes API, e.g., user management)
- SMTP Email Service (third-party or in-house mail server)

B. API Server (Node.js/Express)
1. API Gateway Layer
- index.js (Express app)
- Routes (routes/*.js)
2. Service Layer
- services/*.js – contains business logic, orchestrates data access and external calls (e.g., mailer.js uses nodemailer)
3. Data Access Layer
- model/*.js – interacts with MySQL via queries or ORM
4. Configuration
- config/database_config.js
- config/jwt_secret.js

C. Persistence
- MySQL Database (tables for persons, mailboxes, events, assignments)

##### Relationships and Interactions
- Arduino → HTTP POST → /routes/arduino.js → services/event.js → model/event.js → MySQL
- Admin UI/CLI → HTTP REST → other routes (person, mailbox, assign) → respective services → models → MySQL
- On certain events, services/mailer.js → SMTP Service (via nodemailer) → End-user email inbox
- Authentication: services/login.js uses JWT secret to issue tokens → routes protected by token verification

##### Architectural Patterns & Design Principles
- Layered (Controller/Route → Service → Data Access)
- Single monolithic deployable service
- Separation of concerns: routing vs. business logic vs. persistence
- Config-driven credentials and secrets

- Top layer: Routes (list route files)
- Middle layer: Services (list key services)
- Bottom layer: Models (list key models)
- Sidebar: Config modules (DB, JWT)
- Arduino → Routes/arduino.js → services/event.js
- Admin Client → all other Routes → corresponding Services
- Services/mailer.js → SMTP Server
- Models → MySQL
5) Special flows, e.g., JWT authentication flow at login.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    A[Arduino Device]:::external
    B[Admin Client]:::external
    C[SMTP Server]:::external

    %% API Server
    subgraph "API Server"
        INDEX["index.js"]:::init

        subgraph "Configuration"
            CFG_DB[(Database Config)]:::config
            CFG_JWT[(JWT Secret)]:::config
        end

        subgraph "Routes (Controller Layer)"
            R1["arduino.js"]:::route
            R2["event.js"]:::route
            R3["mailBox.js"]:::route
            R4["mailer.js"]:::route
            R5["person.js"]:::route
        end

        subgraph "Services (Business Logic)"
            S1["event.js"]:::service
            S2["mailbox.js"]:::service
            S3["person.js"]:::service
            S4["assign.js"]:::service
            S5["login.js"]:::service
            S6["mailer.js"]:::service
        end

        subgraph "Models (Data Access)"
            M0["database_connection.js"]:::model
            M1["event.js"]:::model
            M2["mailBox.js"]:::model
            M3["person.js"]:::model
            M4["assign.js"]:::model
        end
    end

    %% Persistence
    DB[(MySQL Database)]:::database
    SC["script_database.sql"]:::script

    %% Connections
    A -->|"POST /arduino"| R1
    B -->|"REST API"| R2
    B -->|"REST API"| R3
    B -->|"REST API"| R4
    B -->|"REST API"| R5

    INDEX -->|"registers routes"| R1
    INDEX --> R2
    INDEX --> R3
    INDEX --> R4
    INDEX --> R5

    R1 -->|"calls Service"| S1
    R2 -->|"calls Service"| S1
    R3 -->|"calls Service"| S2
    R4 -->|"calls Service"| S6
    R5 -->|"calls Service"| S3

    S1 -->|"queries"| M1
    S2 -->|"queries"| M2
    S3 -->|"queries"| M3
    S4 -->|"queries"| M4
    S5 -->|"uses config"| CFG_JWT
    S6 -->|"sends email"| C

    M0 -->|"connects to"| DB
    M1 --> DB
    M2 --> DB
    M3 --> DB
    M4 --> DB

    SC -->|"defines schema"| DB

    %% Click Events
    click INDEX "https://github.com/oussama-sil/sci_api/blob/main/index.js"
    click CFG_DB "https://github.com/oussama-sil/sci_api/blob/main/config/database_config.js"
    click CFG_JWT "https://github.com/oussama-sil/sci_api/blob/main/config/jwt_secret.js"
    click R1 "https://github.com/oussama-sil/sci_api/blob/main/routes/arduino.js"
    click R2 "https://github.com/oussama-sil/sci_api/blob/main/routes/event.js"
    click R3 "https://github.com/oussama-sil/sci_api/blob/main/routes/mailBox.js"
    click R4 "https://github.com/oussama-sil/sci_api/blob/main/routes/mailer.js"
    click R5 "https://github.com/oussama-sil/sci_api/blob/main/routes/person.js"
    click S1 "https://github.com/oussama-sil/sci_api/blob/main/services/event.js"
    click S2 "https://github.com/oussama-sil/sci_api/blob/main/services/mailbox.js"
    click S3 "https://github.com/oussama-sil/sci_api/blob/main/services/person.js"
    click S4 "https://github.com/oussama-sil/sci_api/blob/main/services/assign.js"
    click S5 "https://github.com/oussama-sil/sci_api/blob/main/services/login.js"
    click S6 "https://github.com/oussama-sil/sci_api/blob/main/services/mailer.js"
    click M0 "https://github.com/oussama-sil/sci_api/blob/main/model/database_connection.js"
    click M1 "https://github.com/oussama-sil/sci_api/blob/main/model/event.js"
    click M2 "https://github.com/oussama-sil/sci_api/blob/main/model/mailBox.js"
    click M3 "https://github.com/oussama-sil/sci_api/blob/main/model/person.js"
    click M4 "https://github.com/oussama-sil/sci_api/blob/main/model/assign.js"
    click SC "https://github.com/oussama-sil/sci_api/blob/main/script_database.sql"

    %% Styles
    classDef external fill:#f9c80e,stroke:#333,stroke-width:1px;
    classDef init fill:#42a5f5,stroke:#333,stroke-width:1px;
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef route fill:#4fa3f7,stroke:#333,stroke-width:1px;
    classDef service fill:#49759c,stroke:#333,stroke-width:1px;
    classDef model fill:#70964b,stroke:#333,stroke-width:1px;
    classDef database fill:#66bb6a,stroke:#333,stroke-width:1px;
    classDef script fill:#8bc34a,stroke:#333,stroke-width:1px;
```
