# sws2apps/sws2apps-api architecture

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

- Interactive diagram: https://gitdiagram.com/sws2apps/sws2apps-api
- Repository: https://github.com/sws2apps/sws2apps-api

## Overview

##### Project type and purpose
- This is a backend‐only, full-stack API service written in TypeScript (Node.js) using Express-style routing.
- Purpose: expose endpoints for the “Scheduling Workbox System” family of applications (sws2apps), handle authentication, business logic, localization, and persistence in Firebase (Firestore & Storage), plus send localized email notifications.

##### File structure
- Top level directories:
- src/ – all application code
- src/v3/routes/ – Express routes definitions
- src/v3/controllers/ – controllers implement request handlers
- src/v3/services/ – service layer broken down by responsibility (API adapters, Firebase data access, encryption, iP lookups, etc.)
- src/v3/middleware/ – reusable middleware (auth checks, version checks, request validation)
- src/v3/config/ – environment-specific configurations (DB, Firebase, i18n, mail)
- src/v3/classes/ & src/v3/definition/ – domain models and TypeScript definitions
- src/v3/utils/ – helper functions
- src/v3/views/ – Handlebars templates for email notifications
- Configuration & infra:
- firebase.json, .firebaserc.example – Firebase hosting/emulator settings
- .devcontainer, .github/workflows – dev & CI/CD setup
- crowdin.yml & locales/ – localization pipeline

##### README for additional insights
- Confirms the service is the backend for all sws2apps apps
- Emphasizes email localization via Crowdin

##### Essential elements
- Do not overcrowd with file names; instead group by module/function
- Cross-cutting middleware (auth, version check, request validation)
- How localization files (locales/) feed into i18n_config → email templates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Clients (Web/Mobile)"]:::client

    %% API Layer
    subgraph "API Layer"
        APIGateway["Express API Gateway"]:::gateway
        Middleware["Middleware Pipeline"]:::gateway
        RouteLayer["Route Layer"]:::controllers
        ControllerLayer["Controller Layer"]:::controllers
    end

    %% Service Layer
    subgraph "Service Layer"
        ApiAdapters["API Adapters"]:::service
        FirebaseDAO["Firebase DAOs"]:::service
        EncryptionService["Encryption Service"]:::service
        AuthIPService["IP Lookup & Auth Utils"]:::service
        LoggerService["Logging Service"]:::service
        ValidatorService["Validation Service"]:::service
        CrowdinService["Crowdin Integration"]:::service
    end

    %% Data Stores & External Services
    subgraph "Data & External Services"
        Firestore["Firestore (DB)"]:::storage
        StorageSvc["Storage"]:::storage
        CrowdinExt["Crowdin (i18n)"]:::external
        SMTP["SMTP / Mail Provider"]:::external
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        ClassesNode["Domain Models"]:::model
        DefinitionsNode["Type Definitions"]:::model
        UtilsNode["Utility Functions"]:::model
    end

    %% Configuration & Templates
    subgraph "Configuration & Templates"
        ConfigFirebase["firebase_config.ts"]:::config
        ConfigEnv["dev.config.ts / app.db_config.ts"]:::config
        ConfigI18n["i18n_config.ts"]:::config
        ConfigMail["mail_config.ts"]:::config
        Locales["locales/ & crowdin.yml"]:::config
        Views["Email Templates (views/)"]:::config
    end

    %% Flow
    Client -->|"HTTP Request"| APIGateway
    APIGateway -->|"runs"| Middleware
    Middleware -->|"dispatches to"| RouteLayer
    RouteLayer -->|"calls"| ControllerLayer
    ControllerLayer -->|"invokes"| ApiAdapters
    ControllerLayer --> ApiAdapters
    ControllerLayer --> FirebaseDAO
    ApiAdapters --> FirebaseDAO
    ControllerLayer --> EncryptionService
    ControllerLayer --> AuthIPService
    ControllerLayer --> LoggerService
    ControllerLayer --> ValidatorService
    ControllerLayer --> CrowdinService
    FirebaseDAO --> Firestore
    FirebaseDAO --> StorageSvc
    CrowdinService --> CrowdinExt
    CrowdinService --> Locales
    CrowdinService --> ConfigI18n
    CrowdinService --> ConfigEnv
    SMTP --> Views
    ControllerLayer --> SMTP

    %% Supporting & Config Dependencies
    ApiAdapters --> ConfigEnv
    FirebaseDAO --> ConfigFirebase
    EncryptionService --> ConfigEnv
    AuthIPService --> ConfigEnv
    LoggerService --> ConfigEnv
    ValidatorService --> ConfigEnv
    ClassesNode --> ControllerLayer
    DefinitionsNode --> ControllerLayer
    UtilsNode --> ControllerLayer

    %% Click Events
    click APIGateway "https://github.com/sws2apps/sws2apps-api/blob/main/src/app.ts"
    click APIGateway "https://github.com/sws2apps/sws2apps-api/blob/main/src/index.ts"
    click RouteLayer "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/routes/"
    click ControllerLayer "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/controllers/"
    click Middleware "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/middleware/"
    click ApiAdapters "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/services/api/"
    click FirebaseDAO "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/services/firebase/"
    click EncryptionService "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/services/encryption/encryption.ts"
    click AuthIPService "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/services/ip_details/auth_utils.ts"
    click LoggerService "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/services/logger/logger.ts"
    click ValidatorService "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/services/validator/"
    click CrowdinService "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/services/crowdin/index.ts"
    click ClassesNode "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/classes/"
    click DefinitionsNode "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/definition/"
    click ConfigFirebase "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/config/firebase_config.ts"
    click ConfigEnv "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/config/dev.config.ts"
    click ConfigEnv "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/config/app.db_config.ts"
    click ConfigI18n "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/config/i18n_config.ts"
    click ConfigMail "https://github.com/sws2apps/sws2apps-api/blob/main/src/v3/config/mail_config.ts"
    click Locales "https://github.com/sws2apps/sws2apps-api/tree/main/locales/"
    click Locales "https://github.com/sws2apps/sws2apps-api/blob/main/crowdin.yml"
    click Views "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/views/"
    click UtilsNode "https://github.com/sws2apps/sws2apps-api/tree/main/src/v3/utils/"

    %% Styles
    classDef client fill:#e0f7fa,stroke:#006064,color:#000;
    classDef gateway fill:#e8f5e9,stroke:#2e7d32,color:#000;
    classDef controllers fill:#e3f2fd,stroke:#1565c0,color:#000;
    classDef service fill:#fff3e0,stroke:#ef6c00,color:#000;
    classDef storage fill:#fff9c4,stroke:#f9a825,color:#000;
    classDef external fill:#fff9c4,stroke:#f9a825,color:#000;
    classDef model fill:#eceff1,stroke:#607d8b,color:#000;
    classDef config fill:#fce4ec,stroke:#c2185b,color:#000;
```
