# howsair/server architecture

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

- Interactive diagram: https://gitdiagram.com/howsair/server
- Repository: https://github.com/howsair/server

## Overview

##### Project type and purpose
- This is a backend‐only application named “HowsAir Server.” Its primary role is to provide a RESTful API for storing, querying, and visualizing environmental measurement data.
- Key technologies: Node.js, Express, TypeScript, PostgreSQL (via Prisma ORM), cron jobs for scheduled map generation, external services (Cloudinary, email), Docker/Docker Compose for containerization, and Vitest for tests.

##### File structure
- Top-level folders and files
– src/ – application code (app.ts, controllers, routes, services, middleware, cron jobs, utilities, types)
– prisma/ – database schema, migrations, seed script
– docs/ – auto-generated API and code documentation
– test/ – unit tests organized by feature area
– Dockerfile, docker-compose.yml – containerization setup
– .github/workflows/ci.yml – CI pipeline for building, testing, linting
- Architectural patterns
– Layered MVC-style separation: routes → controllers → services → Prisma client (data layer)
– Middleware pipeline for authentication, error handling
– Scheduled tasks module (src/cron/jobs) that runs on a schedule to generate air quality maps and push to Cloudinary
– Utility modules for cross-cutting concerns (authUtils, emailSenderUtils, map generation, validators)

##### README for additional insights
- Describes local development workflow (npm run setup spins up PostgreSQL, seeds data, Prisma Studio)
- CI uses Vitest for unit tests
- Production uses Docker Compose to stand up backend and database containers, optional HTTPS via self-signed certs, and static compilation of a separate frontend client.
- External integrations: Cloudinary for image storage, email provider for verification/reset, SonarQube for code quality.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Containers
    subgraph "API Container" 
        direction TB
        subgraph "Express Application"
            direction TB
            %% Middleware Layer
            subgraph "Middleware Layer"
                direction TB
                AuthMW["Authentication Middleware"]:::middleware
                ErrorMW["Error Handling Middleware"]:::middleware
            end

            %% Routing Layer
            subgraph "Routing Layer"
                direction TB
                MainRouter["Main Router"]:::route
                AuthRoutes["Auth Routes"]:::route
                UsersRoutes["Users Routes"]:::route
                MeasurementsRoutes["Measurements Routes"]:::route
                NodesRoutes["Nodes Routes"]:::route
                MapsRoutes["AirQualityMaps Routes"]:::route
                CheckoutRoutes["Checkout Routes"]:::route
            end

            %% Controller Layer
            subgraph "Controller Layer"
                direction TB
                AuthCtrl["AuthController"]:::controller
                UsersCtrl["UsersController"]:::controller
                MeasurementsCtrl["MeasurementsController"]:::controller
                NodesCtrl["NodesController"]:::controller
                MapsCtrl["AirQualityMapsController"]:::controller
                CheckoutCtrl["CheckoutController"]:::controller
            end

            %% Service Layer
            subgraph "Service Layer"
                direction TB
                AuthService["authService"]:::service
                UsersService["usersService"]:::service
                MeasurementsService["measurementsService"]:::service
                NodesService["nodesService"]:::service
                CacheService["cacheService"]:::service
                CloudinaryService["cloudinaryService"]:::service
                DailyStatsService["dailyStatsService"]:::service
                HistoricMapsService["historicAirQualityMapsService"]:::service
            end

            %% Prisma Data Layer
            PrismaClient["Prisma Client"]:::db
        end

        %% Cron Worker
        subgraph "Scheduler"
            direction TB
            CronInit["Cron Initialization"]:::cron
            AirMapJob["AirQualityMapJob"]:::cron
        end
    end

    %% External Components
    subgraph "External Systems"
        direction TB
        Postgres["PostgreSQL"]:::db
        CacheStore["Cache Store (Redis)"]:::db
        Cloudinary["Cloudinary"]:::external
        EmailService["Email Provider"]:::external
    end

    %% CI/CD & Infra
    subgraph "DevOps & CI/CD"
        direction TB
        DockerCompose["Docker Compose"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        SonarQube["SonarQube"]:::infra
    end

    %% Utilities (cross-cutting)
    subgraph "Utilities"
        direction TB
        AuthUtils["authUtils"]:::utils
        EmailUtils["emailSenderUtils"]:::utils
        MapUtils["generateMapUtils"]:::utils
        AirQualityUtils["airQualityUtils"]:::utils
        Validators["validatorsUtils"]:::utils
    end

    %% Entry Points
    AppTS["app.ts"]:::infra
    IndexTS["index.ts"]:::infra

    %% Flows
    AppTS -->|uses| AuthMW
    AppTS -->|uses| ErrorMW
    AuthMW --> MainRouter
    ErrorMW --> MainRouter

    MainRouter --> AuthRoutes
    MainRouter --> UsersRoutes
    MainRouter --> MeasurementsRoutes
    MainRouter --> NodesRoutes
    MainRouter --> MapsRoutes
    MainRouter --> CheckoutRoutes

    AuthRoutes --> AuthCtrl
    UsersRoutes --> UsersCtrl
    MeasurementsRoutes --> MeasurementsCtrl
    NodesRoutes --> NodesCtrl
    MapsRoutes --> MapsCtrl
    CheckoutRoutes --> CheckoutCtrl

    AuthCtrl --> AuthService
    UsersCtrl --> UsersService
    MeasurementsCtrl --> MeasurementsService
    NodesCtrl --> NodesService
    MapsCtrl --> HistoricMapsService
    CheckoutCtrl --> AuthService

    %% Services to DB and Utils
    AuthService -->|reads/writes| PrismaClient
    UsersService -->|reads/writes| PrismaClient
    MeasurementsService -->|reads/writes| PrismaClient
    NodesService -->|reads/writes| PrismaClient
    HistoricMapsService -->|writes metadata| PrismaClient

    MeasurementsService --> CacheService
    CacheService --> CacheStore

    CloudinaryService --> Cloudinary
    HistoricMapsService --> CloudinaryService
    HistoricMapsService --> MapUtils
    MapUtils -->|uses| AirQualityUtils

    AuthService --> EmailUtils
    EmailUtils --> EmailService

    %% Cron flow
    CronInit --> AirMapJob
    AirMapJob --> HistoricMapsService

    %% DB connections
    PrismaClient --> Postgres

    %% DevOps
    DockerCompose -->|orchestrates| AppTS
    DockerCompose -->|orchestrates| Postgres
    DockerCompose -->|optional| CacheStore

    GitHubActions -->|runs| TestSuite["Vitest Test Suite"]:::infra
    GitHubActions -->|runs| Linting["ESLint/TypeScript Lint"]:::infra
    GitHubActions -->|scans| SonarQube

    %% Click Events
    click AppTS "https://github.com/howsair/server/blob/master/src/app.ts"
    click IndexTS "https://github.com/howsair/server/blob/master/src/index.ts"
    click AuthMW "https://github.com/howsair/server/blob/master/src/middleware/auth.ts"
    click ErrorMW "https://github.com/howsair/server/blob/master/src/middleware/errorHandler.ts"
    click MainRouter "https://github.com/howsair/server/blob/master/src/routes/router.ts"
    click AuthRoutes "https://github.com/howsair/server/blob/master/src/routes/authRoutes.ts"
    click UsersRoutes "https://github.com/howsair/server/blob/master/src/routes/usersRoutes.ts"
    click MeasurementsRoutes "https://github.com/howsair/server/blob/master/src/routes/measurementsRoutes.ts"
    click NodesRoutes "https://github.com/howsair/server/blob/master/src/routes/nodesRoutes.ts"
    click MapsRoutes "https://github.com/howsair/server/blob/master/src/routes/airQualityMapsRoutes.ts"
    click CheckoutRoutes "https://github.com/howsair/server/blob/master/src/routes/checkoutRoutes.ts"
    click AuthCtrl "https://github.com/howsair/server/blob/master/src/controllers/authController.ts"
    click UsersCtrl "https://github.com/howsair/server/blob/master/src/controllers/usersController.ts"
    click MeasurementsCtrl "https://github.com/howsair/server/blob/master/src/controllers/measurementsController.ts"
    click NodesCtrl "https://github.com/howsair/server/blob/master/src/controllers/nodesController.ts"
    click MapsCtrl "https://github.com/howsair/server/blob/master/src/controllers/airQualityMapsController.ts"
    click CheckoutCtrl "https://github.com/howsair/server/blob/master/src/controllers/checkoutController.ts"
    click AuthService "https://github.com/howsair/server/blob/master/src/services/authService.ts"
    click UsersService "https://github.com/howsair/server/blob/master/src/services/usersService.ts"
    click MeasurementsService "https://github.com/howsair/server/blob/master/src/services/measurementsService.ts"
    click NodesService "https://github.com/howsair/server/blob/master/src/services/nodesService.ts"
    click CacheService "https://github.com/howsair/server/blob/master/src/services/cacheService.ts"
    click CloudinaryService "https://github.com/howsair/server/blob/master/src/services/cloudinaryService.ts"
    click DailyStatsService "https://github.com/howsair/server/blob/master/src/services/dailyStatsService.ts"
    click HistoricMapsService "https://github.com/howsair/server/blob/master/src/services/historicAirQualityMapsService.ts"
    click PrismaClient "https://github.com/howsair/server/blob/master/src/libs/prisma.ts"
    click CronInit "https://github.com/howsair/server/blob/master/src/cron/index.ts"
    click AirMapJob "https://github.com/howsair/server/blob/master/src/cron/jobs/airQualityMapJob.ts"
    click AuthUtils "https://github.com/howsair/server/blob/master/src/utils/authUtils.ts"
    click EmailUtils "https://github.com/howsair/server/blob/master/src/utils/emailSenderUtils.ts"
    click MapUtils "https://github.com/howsair/server/blob/master/src/utils/maps/generateMapUtils.ts"
    click AirQualityUtils "https://github.com/howsair/server/blob/master/src/utils/airQualityUtils.ts"
    click Validators "https://github.com/howsair/server/blob/master/src/utils/validatorsUtils.ts"
    click DockerCompose "https://github.com/howsair/server/blob/master/docker-compose.yml"
    click GitHubActions "https://github.com/howsair/server/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef middleware fill:#f9f,stroke:#333,stroke-width:1px
    classDef route fill:#bbf,stroke:#333,stroke-width:1px
    classDef controller fill:#bfb,stroke:#333,stroke-width:1px
    classDef service fill:#ffb,stroke:#333,stroke-width:1px
    classDef db fill:#fbb,stroke:#333,stroke-width:1px
    classDef external fill:#fbf,stroke:#333,stroke-width:1px
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef utils fill:#ffd,stroke:#333,stroke-width:1px
    classDef cron fill:#dff,stroke:#333,stroke-width:1px
```
