🚀 Alerta Cidadão API (Core Service)

The backend powerhouse behind the Alerta Cidadão platform, designed for high availability and event-driven processing.

---

🔗 Live Documentation & Access

🟢 Live Swagger UI: https://api.alertacidadaoapi.com/api
(Try the endpoints directly in your browser!)

---

📖 Context: The Evolution

This project represents a significant architectural evolution. Originally built with Express.js (MVP), this system has been completely re-engineered using NestJS.

The goal was to transition from a monolithic script to a Enterprise-Grade Architecture, leveraging:

• Event-Driven Design with RabbitMQ (to handle heavy background tasks).
• Real-Time Communication via WebSockets.
• Relational Integrity with PostgreSQL & Prisma.
• Automated CI/CD Pipelines for reliable deployments on Azure.

🏗️ Architecture & Infrastructure

The system is deployed on Microsoft Azure using a containerized strategy optimized for performance and cost-efficiency.

graph LR
    User((Usuário))
    
    subgraph Frontend_App ["Frontend (Vercel)"]
        Next["Next.js Client"]
    end

    subgraph Internet ["Internet / DNS"]
        Domain["api.alertacidadaoapi.com"]
    end

    subgraph Azure_Infra ["Azure Cloud (Canadá)"]
        direction TB
        
        subgraph VM ["Azure VM (Linux)"]
            Nginx["Nginx (Reverse Proxy + SSL)"]
            
            subgraph Containers ["Docker Compose Cluster"]
                API["NestJS API"]
                DB[("PostgreSQL")]
                Rabbit[("RabbitMQ")]
                Redis[("Redis")]
            end
        end
    end
    
    %% CI/CD Flow
    GitHub["GitHub Repo"] -. "Actions CI/CD" .-> VM

    %% User Flow
    User -->|Acessa| Next
    
    %% Requests Flow
    Next -- "HTTPS" --> Domain
    User -- "WSS (WebSocket)" --> Domain
    
    %% Ingress Flow
    Domain -- "Port 443" --> Nginx
    
    %% Internal Docker Networking
    Nginx -- "Proxy Pass :3000" --> API
    
    API <-->|"Prisma"| DB
    API <-->|"Events"| Rabbit
    API <-->|"Cache/WS"| Redis

    %% ESTILIZAÇÃO (High Contrast)
    %% Cores fortes com texto branco para leitura fácil
    
    %% Azul para o Core (API, Banco, Fila)
    classDef container fill:#2962ff,stroke:#0039cb,stroke-width:2px,color:#ffffff;
    
    %% Verde para Entrada/Segurança (Nginx)
    classDef gateway fill:#00c853,stroke:#009624,stroke-width:2px,color:#ffffff;
    
    %% Amarelo para o DNS (Destaque visual de conexão)
    classDef dns fill:#ffd600,stroke:#fbc02d,stroke-width:2px,color:#000000;
    
    %% Cinza Escuro para Externos (User, Git, Vercel)
    classDef external fill:#263238,stroke:#000000,stroke-width:2px,color:#ffffff;
    
    %% Fundo da Cloud mais neutro
    classDef cloud fill:#f5f5f5,stroke:#90a4ae,stroke-width:2px,stroke-dasharray: 5 5,color:#37474f;
    
    %% Aplicando as classes
    class API,DB,Rabbit,Redis container;
    class Nginx gateway;
    class Domain dns;
    class GitHub,Next,User external;
    class Azure_Infra,VM cloud;

Loading

✨ Key Engineering Features

• Event-Driven Architecture: Uses RabbitMQ to decouple PDF generation from the main API. The API returns 202 Accepted immediately, and the heavy processing happens in the background.
• Real-Time Feedback: MOnce the background job is done, the server pushes the result to the client via WebSockets.
• Modular Design: Strictly follows NestJS modular architecture (Controllers, Services, Guards, DTOs).
• Security:
  • JWT Authentication (Middleware integrated with Firebase Auth).
  • Data Validation using class-validator and DTOs.
  • Rate Limiting (Throttler) to prevent abuse.
• Testing:
  • Unit Tests (Jest) for business logic.
  • E2E Tests (Supertest) for critial endpoints.

☁️ DevOps Strategy

• CI/CD: GitHub Actions pipeline runs tests, builds the Docker image, and deploys to Azure via SSH.
• Docker: Multi-stage builds (Alpine Linux) to minimize image size and RAM usage.
• Nginx: Configured as a Reverse Proxy with SSL termination (Let's Encrypt) to secure traffic.

🛠️ Tech Stack

• Framework: NestJS
• Message Broker: RabbitMQ
• Database: PostgreSQL + Prisma ORM
• Cache/WS Adapter: Redis
• Cloud: Microsoft Azure (Virtual Machines)
• Containerization: Docker & Docker Compose

🚀 Getting Started

Follow these steps to run the complete stack locally (API + DB + RabbitMQ + Redis).

Prerequisites

• Node.js (v18+)
• Docker & Docker Compose

Installation

1. Clone the repository

git clone https://github.com/copa-origem/alerta-cidadao-api.git
cd alerta-cidadao-api

2. Install dependencies

npm install

3. Environment Setup
   Create a .env file in the root directory based on .env.example

DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb?schema=public"
CLOUDINARY_NAME="your_cloudinary_name"
CLOUDINARY_API_KEY="your_api_cloudinary_key"
CLOUDINARY_API_SECRET="your_cloudinary_api_secret"
# Default local RabbitMQ connection
RABBITMQ_URL="amqp://guest:guest@localhost:5672"

Note: You must place your firebase-config.json in the root folder for JWT Auth to work.

4. Start Infrastructure (DB, Rabbit, Redis)

docker compose up -d

5. Database Migration & Seeding

npx prisma migrate dev
npx prisma db seed

6. Run the Application

npm run start:dev

Access Swagger at: http://localhost:3000/api

🧪 Running Tests

To ensure everything is working correctly, run the test suites:

# Unit tests
npm run test

# End-to-End tests
npm run test:e2e

# Test coverage
npm run test:cov

👤 Author

Rafael Silva Rangel de Almeida

• Linkedin: https://www.linkedin.com/in/rafael-rangel1/
• GitHub: @Rafael19722
• Portfolio: https://rafaelrangel.vercel.app/

Made with 💜 and TypeScript.