# jietrylcanete/maintenance_api architecture

> Architecture diagram of the GitHub repository jietrylcanete/maintenance_api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jietrylcanete/maintenance_api
- Repository: https://github.com/jietrylcanete/maintenance_api

## Overview

This is a school-maintenance API: users submit and track requests, while staff/admins manage assignment and status. Request creation invokes AI classification and automatic staff assignment, then records activity; attachments are uploaded separately. Accounts provide authentication, verification, password recovery, preferences, and administration, while activity logs provide filtered, role-aware history. The excerpts show the main routing and several service calls; unsampled modules are included only for documented capabilities, with uncertain connections omitted.

Main entry points: [`_helpers/db.js`](https://github.com/jietrylcanete/maintenance_api/blob/main/_helpers/db.js) (MySQL database), [`maintenance/maintenance.controller.js`](https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance.controller.js) (Maintenance routes), [`server.js`](https://github.com/jietrylcanete/maintenance_api/blob/main/server.js) (HTTP server), [`accounts/account.service.js`](https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.service.js) (Account service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_server["HTTP server<br/>[server.js]"]
end

subgraph group_identity["Accounts and access"]
  node_account_routes["Account routes"]
  node_account_service["Account service<br/>[account.service.js]"]
  node_account_model["Account model<br/>[account.model.js]"]
  node_refresh_model["Refresh tokens"]
  node_preferences["Preferences"]
end

subgraph group_maintenance["Maintenance workflow"]
  node_maintenance_routes["Maintenance routes"]
  node_request_model["Request records"]
  node_attachment_model["Attachment records"]
  node_upload["Image upload"]
  node_ai["Request classification<br/>[ai.service.js]"]
end

subgraph group_history["Activity history"]
  node_activity_routes["Activity routes"]
  node_activity_service["Activity service"]
  node_activity_model["Activity records"]
end

subgraph group_platform["Persistence and integrations"]
  node_database[("MySQL database<br/>[db.js]")]
  node_email["Email delivery<br/>[send-email.js]"]
end

node_client(("API client"))
node_gemini{{"Google Gemini"}}

node_client -->|"sends requests"| node_server
node_server -->|"routes accounts"| node_account_routes
node_server -->|"routes maintenance"| node_maintenance_routes
node_server -->|"routes activity"| node_activity_routes
node_account_routes -->|"calls"| node_account_service
node_account_service -->|"logs account events"| node_activity_service
node_account_service -->|"sends mail"| node_email
node_maintenance_routes -->|"classifies requests"| node_ai
node_ai -->|"requests generation"| node_gemini
node_maintenance_routes -->|"accepts images"| node_upload
node_maintenance_routes -->|"logs workflow events"| node_activity_service
node_activity_routes -->|"queries logs"| node_activity_service
node_activity_service -->|"reads and writes"| node_activity_model
node_account_service -->|"uses account data"| node_database
node_maintenance_routes -->|"uses request data"| node_database
node_database -->|"initializes"| node_account_model
node_database -->|"initializes"| node_refresh_model
node_database -->|"initializes"| node_preferences
node_database -->|"initializes"| node_request_model
node_database -->|"initializes"| node_attachment_model
node_database -->|"initializes"| node_activity_model

click node_server "https://github.com/jietrylcanete/maintenance_api/blob/main/server.js"
click node_account_routes "https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.controller.js"
click node_account_service "https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.service.js"
click node_account_model "https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.model.js"
click node_refresh_model "https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/refresh-token.model.js"
click node_preferences "https://github.com/jietrylcanete/maintenance_api/blob/main/models/preferences.model.js"
click node_maintenance_routes "https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance.controller.js"
click node_request_model "https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance-request.model.js"
click node_attachment_model "https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance-attachment.model.js"
click node_upload "https://github.com/jietrylcanete/maintenance_api/blob/main/uploads/maintenance-images/upload.middleware.js"
click node_ai "https://github.com/jietrylcanete/maintenance_api/blob/main/services/ai.service.js"
click node_activity_routes "https://github.com/jietrylcanete/maintenance_api/blob/main/activity/activity.controller.js"
click node_activity_service "https://github.com/jietrylcanete/maintenance_api/blob/main/activity/activity.service.js"
click node_activity_model "https://github.com/jietrylcanete/maintenance_api/blob/main/models/activitylog.model.js"
click node_database "https://github.com/jietrylcanete/maintenance_api/blob/main/_helpers/db.js"
click node_email "https://github.com/jietrylcanete/maintenance_api/blob/main/_helpers/send-email.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_client toneBlue
class node_account_routes,node_account_service,node_account_model,node_refresh_model,node_preferences toneAmber
class node_maintenance_routes,node_request_model,node_attachment_model,node_upload,node_ai toneMint
class node_activity_routes,node_activity_service,node_activity_model toneRose
class node_database,node_email,node_gemini toneIndigo
```

## Components

### API entry

- [HTTP server](https://github.com/jietrylcanete/maintenance_api/blob/main/server.js): `server.js`

### Accounts and access

- [Account routes](https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.controller.js): `accounts/account.controller.js`
- [Account service](https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.service.js): `accounts/account.service.js`
- [Account model](https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/account.model.js): `accounts/account.model.js`
- [Refresh tokens](https://github.com/jietrylcanete/maintenance_api/blob/main/accounts/refresh-token.model.js): `accounts/refresh-token.model.js`
- [Preferences](https://github.com/jietrylcanete/maintenance_api/blob/main/models/preferences.model.js): `models/preferences.model.js`

### Maintenance workflow

- [Maintenance routes](https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance.controller.js): `maintenance/maintenance.controller.js`
- [Request records](https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance-request.model.js): `maintenance/maintenance-request.model.js`
- [Attachment records](https://github.com/jietrylcanete/maintenance_api/blob/main/maintenance/maintenance-attachment.model.js): `maintenance/maintenance-attachment.model.js`
- [Image upload](https://github.com/jietrylcanete/maintenance_api/blob/main/uploads/maintenance-images/upload.middleware.js): `uploads/maintenance-images/upload.middleware.js`
- [Request classification](https://github.com/jietrylcanete/maintenance_api/blob/main/services/ai.service.js): `services/ai.service.js`

### Activity history

- [Activity routes](https://github.com/jietrylcanete/maintenance_api/blob/main/activity/activity.controller.js): `activity/activity.controller.js`
- [Activity service](https://github.com/jietrylcanete/maintenance_api/blob/main/activity/activity.service.js): `activity/activity.service.js`
- [Activity records](https://github.com/jietrylcanete/maintenance_api/blob/main/models/activitylog.model.js): `models/activitylog.model.js`

### Persistence and integrations

- [MySQL database](https://github.com/jietrylcanete/maintenance_api/blob/main/_helpers/db.js): `_helpers/db.js`
- [Email delivery](https://github.com/jietrylcanete/maintenance_api/blob/main/_helpers/send-email.js): `_helpers/send-email.js`

### Other components

- **API client**
- **Google Gemini**

## Connections

- API client → HTTP server: sends requests (evidence: `server.js`)
- HTTP server → Account routes: routes accounts (evidence: `server.js`)
- HTTP server → Maintenance routes: routes maintenance (evidence: `server.js`)
- HTTP server → Activity routes: routes activity (evidence: `server.js`)
- Account routes → Account service: calls (evidence: `accounts/account.controller.js`)
- Account service → Activity service: logs account events (evidence: `accounts/account.service.js`)
- Account service → Email delivery: sends mail (evidence: `accounts/account.service.js`)
- Maintenance routes → Request classification: classifies requests (evidence: `maintenance/maintenance.controller.js`)
- Request classification → Google Gemini: requests generation (evidence: `services/ai.service.js`)
- Maintenance routes → Image upload: accepts images (evidence: `maintenance/maintenance.controller.js`)
- Maintenance routes → Activity service: logs workflow events (evidence: `maintenance/maintenance.controller.js`)
- Activity routes → Activity service: queries logs (evidence: `activity/activity.controller.js`)
- Activity service → Activity records: reads and writes (evidence: `activity/activity.service.js`)
- Account service → MySQL database: uses account data (evidence: `_helpers/db.js`)
- Maintenance routes → MySQL database: uses request data (evidence: `_helpers/db.js`)
- MySQL database → Account model: initializes (evidence: `_helpers/db.js`)
- MySQL database → Refresh tokens: initializes (evidence: `_helpers/db.js`)
- MySQL database → Preferences: initializes (evidence: `_helpers/db.js`)
- MySQL database → Request records: initializes (evidence: `_helpers/db.js`)
- MySQL database → Attachment records: initializes (evidence: `_helpers/db.js`)
- MySQL database → Activity records: initializes (evidence: `_helpers/db.js`)