# rteixe0/apae-backend architecture

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

- Interactive diagram: https://gitdiagram.com/rteixe0/apae-backend
- Repository: https://github.com/rteixe0/apae-backend

## Overview

##### Project type and purpose
- This is a **full-stack back-end API** (Node.js + Express) for managing events and tickets for APAE.
- It exposes REST endpoints for events, tickets, and validation, uses Firebase for auth, Firestore for data persistence, Storage for QR codes, and Node libraries for email and QR generation.

##### File structure
- Top-level:
- index.js – application entrypoint
- controllers/ – request handlers (eventsController, ticketsController, validationController)
- routes/ – route definitions mapping URLs to controllers
- middlewares/ – authMiddleware for JWT validation via Firebase
- services/ – low-level business logic (emailService, qrService)
- config/ – Firebase, email (SMTP) and storage configuration
- scripts/ – admin scripts for Firestore setup, token retrieval, custom claims
- webhook.js – standalone integration endpoint
- .github/workflows/deploy.yml – CI/CD pipeline
- Key patterns:
- Layered MVC-style (Routes → Controllers → Services → Data layer)
- BaaS integration via Firebase Admin SDK

##### Additional insights from README
- Uses environment variables for Firebase credentials and SMTP.
- Deploys to a Google Cloud VM via GitHub Actions.
- QR Codes are generated at runtime and stored in Firebase Storage.

a. Main components
1. Client(s)
– Frontend app, Postman, mobile apps generating HTTP requests
2. API Layer (Express)
– Routes
– Authentication Middleware (verifies JWT against Firebase Auth)
– Controllers (orchestrate use cases)
– Services (emailService, qrService)
3. Firebase BaaS
– Auth (JWT validation & custom claims)
– Firestore (Events, Tickets, Validations collections)
– Storage (QR code images)
4. External SMTP server (Gmail SMTP)
5. CI/CD Pipeline (GitHub Actions → Google Cloud VM)
b. Relationships & interactions
1. Client makes HTTP request → Express Routes
2. Route calls Auth Middleware → verifies JWT with Firebase Auth
3. Controller executes business logic → may invoke:
- qrService to generate QR code
- emailService to send ticket via SMTP
- Firestore via Firebase Admin to read/write data
- Firebase Storage to upload QR image
4. Response flows back to client
5. CI/CD: on merge to main → GitHub Actions runs deploy.yml → SSH/git pull on GCE VM → restarts Node service
c. Architectural patterns & principles
- **Layered architecture**: clear separation of routing, business logic, data access
- **Dependency inversion**: controllers depend on abstracted services (email, qr, database via Firebase Admin)
- **Externalized configuration**: all credentials in env
- **Serverless-style backend**: relies on third-party BaaS rather than custom DB servers
d. Key technologies/frameworks
- Node.js, Express
- Firebase Admin SDK (Auth, Firestore, Storage)
- Nodemailer (SMTP)
- QRCode library
- dotenv, cors, body-parser
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    subgraph "Client"
        Client["Client (Frontend / Postman / Mobile)"]:::client
    end

    subgraph "API Layer"
        direction TB
        Entry["index.js"]:::api
        subgraph "Routes"
            direction TB
            EventsRoutes["Events Routes"]:::api
            TicketsRoutes["Tickets Routes"]:::api
            ValidationRoutes["Validation Routes"]:::api
        end
        AuthMW["Auth Middleware"]:::api
        subgraph "Controllers"
            direction TB
            EventsCtrl["EventsController"]:::api
            TicketsCtrl["TicketsController"]:::api
            ValidationCtrl["ValidationController"]:::api
        end
        subgraph "Services"
            direction TB
            EmailSvc["Email Service"]:::api
            QRSvc["QR Service"]:::api
        end
        subgraph "Config"
            direction TB
            FirebaseCfg["Firebase Config"]:::api
            EmailCfg["Email Config"]:::api
            StorageCfg["Storage Config"]:::api
        end
        Webhook["webhook.js"]:::api
    end

    subgraph "Admin Scripts"
        direction TB
        CreateCols["criarColecoes.js"]:::api
        LoginToken["loginAndGetToken.js"]:::api
        SetClaims["setCustomClaim.js"]:::api
    end

    subgraph "Firebase BaaS"
        direction TB
        Auth["Firebase Auth"]:::baas
        Firestore["Firestore"]:::baas
        Storage["Storage (QR Images)"]:::baas
    end

    SMTP["SMTP Service (Gmail)"]:::external

    subgraph "CI/CD Pipeline"
        direction TB
        GHActions["GitHub Actions"]:::external
        ProdVM["Google Cloud VM"]:::external
    end

    %% Connections
    Client -->|HTTP| Entry
    Entry --> EventsRoutes
    Entry --> TicketsRoutes
    Entry --> ValidationRoutes
    Entry --> Webhook
    EventsRoutes -->|uses| AuthMW
    TicketsRoutes -->|uses| AuthMW
    ValidationRoutes -->|uses| AuthMW
    AuthMW -->|verifies JWT| Auth

    EventsRoutes -->|calls| EventsCtrl
    TicketsRoutes -->|calls| TicketsCtrl
    ValidationRoutes -->|calls| ValidationCtrl

    EventsCtrl -->|reads/writes| Firestore
    TicketsCtrl -->|reads/writes| Firestore
    ValidationCtrl -->|reads/writes| Firestore

    TicketsCtrl -->|generate QR| QRSvc
    QRSvc -->|upload| Storage
    TicketsCtrl -->|send email| EmailSvc
    EmailSvc -->|SMTP| SMTP

    Entry -->|loads| FirebaseCfg
    Entry -->|loads| EmailCfg
    Entry -->|loads| StorageCfg

    GHActions -.->|deploy| ProdVM
    ProdVM -->|runs| Entry

    %% Click Events
    click Entry "https://github.com/rteixe0/apae-backend/blob/main/index.js"
    click EventsRoutes "https://github.com/rteixe0/apae-backend/blob/main/routes/events.js"
    click TicketsRoutes "https://github.com/rteixe0/apae-backend/blob/main/routes/tickets.js"
    click ValidationRoutes "https://github.com/rteixe0/apae-backend/blob/main/routes/validation.js"
    click EventsCtrl "https://github.com/rteixe0/apae-backend/blob/main/controllers/eventsController.js"
    click TicketsCtrl "https://github.com/rteixe0/apae-backend/blob/main/controllers/ticketsController.js"
    click ValidationCtrl "https://github.com/rteixe0/apae-backend/blob/main/controllers/validationController.js"
    click AuthMW "https://github.com/rteixe0/apae-backend/blob/main/middlewares/authMiddleware.js"
    click EmailSvc "https://github.com/rteixe0/apae-backend/blob/main/services/emailService.js"
    click QRSvc "https://github.com/rteixe0/apae-backend/blob/main/services/qrService.js"
    click FirebaseCfg "https://github.com/rteixe0/apae-backend/blob/main/config/firebase.js"
    click EmailCfg "https://github.com/rteixe0/apae-backend/blob/main/config/emailService.js"
    click StorageCfg "https://github.com/rteixe0/apae-backend/blob/main/config/storage.js"
    click CreateCols "https://github.com/rteixe0/apae-backend/blob/main/scripts/criarColecoes.js"
    click LoginToken "https://github.com/rteixe0/apae-backend/blob/main/scripts/loginAndGetToken.js"
    click SetClaims "https://github.com/rteixe0/apae-backend/blob/main/scripts/setCustomClaim.js"
    click Webhook "https://github.com/rteixe0/apae-backend/blob/main/webhook.js"
    click GHActions "https://github.com/rteixe0/apae-backend/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef api fill:#D6E9FE,stroke:#333,stroke-width:1px
    classDef baas fill:#DFF0D8,stroke:#333,stroke-width:1px
    classDef external fill:#FCF8E3,stroke:#333,stroke-width:1px
    classDef client fill:#EEEEEE,stroke:#333,stroke-width:1px
```
