# muito-alem-do-microfone/bsb-api architecture

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

- Interactive diagram: https://gitdiagram.com/muito-alem-do-microfone/bsb-api
- Repository: https://github.com/muito-alem-do-microfone/bsb-api

## Overview

##### Project Type and Purpose
- This is a monolithic REST‐based backend API (“BSB API”) built with Node.js and Express.
- It exposes CRUD endpoints for announcements, genres, instruments, tags, and Brazilian states.
- It integrates with external systems: PostgreSQL via Prisma, AWS S3 for image storage, MailerSend for email, Discord webhooks for notifications.
- It includes CI/CD (GitHub Actions + Docker), schema migrations, and seed data.

##### File Structure Analysis
- Top level:
- server.js (Express app entry point)
- Dockerfile, .github/workflows (CI/CD)
- prisma/ (schema, migrations, seed scripts)
- src/:
- config/ (DB config)
- controllers/ (business‐logic entry points)
- routes/ (Express route definitions)
- middlewares/ (e.g., file uploads)
- services/ (email, S3 upload modules)
- utils/ (shared helpers)
- test/ (Vitest + Supertest tests)
- package.json, husky config for pre‐commit hooks.

##### README Insights
- Describes core features and tech stack.
- Mentions Docker & docker-compose for deployment.
- References external docs for API spec.

##### Main Components
a. Clients: any frontend or third‐party system consuming the API.
b. API Layer (Express server):
- Routes → Controllers → Services pattern
- Middlewares (upload)
c. Business Logic / Services:
- Prisma client to PostgreSQL
- S3 upload service
- Email service (MailerSend)
- Discord webhook integration
d. Data Storage:
- PostgreSQL database
- S3 bucket (images)
e. CI/CD Pipeline:
- GitHub Actions → Docker build → Deploy
f. Development Tools:
- Prisma migrations & seeders
- Vitest tests

##### Relationships and Data Flows
- Client → HTTP request → Express routes
- Routes call Controllers → Controllers call Services
- Services call:
- Prisma client → PostgreSQL
- AWS SDK S3 → S3 bucket
- MailerSend API → email system
- Discord webhook endpoint
- CI/CD: Git push → GitHub Actions → Docker image → Production host

##### Architectural Patterns and Principles
- Layered architecture (Presentation → Controller → Service → Data Access)
- Separation of concerns: controllers don’t access DB directly; services encapsulate external calls.
- Infrastructure as code: Prisma schema & migrations manage DB.
- 12-factor app principles (config via env, stateless server, backing services).

##### Technologies and Frameworks
- Node.js, Express
- Prisma ORM + PostgreSQL
- AWS SDK v3 (S3)
- MailerSend (email)
- Discord webhooks (notifications)
- Docker, docker-compose
- Vitest + Supertest for testing
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        Client["Frontend/Mobile Apps"]:::external
        ThirdParty["Third-Party Systems"]:::external
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Server["Express Server\n(server.js)"]:::code
        subgraph "Routes" 
            direction TB
            MainRouter["Index Router"]:::code
            AnnRoute["Announcement Routes"]:::code
            GenreRoute["Genre Routes"]:::code
            InstRoute["Instrument Routes"]:::code
            TagRoute["Tag Routes"]:::code
            StatesRoute["States Routes"]:::code
            FormDataRoute["FormData Routes"]:::code
        end
        subgraph "Controllers"
            direction TB
            CtrlIndex["Controllers Index"]:::code
            AnnCtrl["Announcement Controller"]:::code
            GenreCtrl["Genre Controller"]:::code
            InstCtrl["Instrument Controller"]:::code
            TagCtrl["Tag Controller"]:::code
            StatesCtrl["States Controller"]:::code
            FormDataCtrl["FormData Controller"]:::code
        end
        UploadMW["Upload Middleware"]:::code
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        DBConfig["Prisma Client\n(db.config.js)"]:::service
        S3Service["S3 Upload Service"]:::service
        EmailService["Email Service"]:::service
        EmailTpl["Email Templates"]:::service
        DiscordSvc["Discord Webhook"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres[(PostgreSQL DB)]:::db
        S3Bucket["AWS S3 Bucket"]:::external
        MailerSend["MailerSend API"]:::external
        DiscordAPI["Discord Webhook Endpoint"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GitPush["Git Push"]:::code
        GHActions["GitHub Actions\n(.github/workflows)"]:::code
        DockerBuild["Docker Build\n(Dockerfile)"]:::code
        Deploy["Deploy to Production"]:::code
        Migrations["Prisma Migrations\n(prisma/migrations/)"]:::service
        Seed["Seed Scripts\n(prisma/seed.js)"]:::service
    end

    %% Test Tools
    subgraph "Testing & Utils"
        direction TB
        Vitest["Vitest Config"]:::code
        TestAnn["Announcement Tests"]:::code
        TestGenre["Genre Tests"]:::code
        TestInst["Instrument Tests"]:::code
        TestTag["Tag Tests"]:::code
        TestStates["States Tests"]:::code
        Utils["Utilities"]:::code
        Package["package.json"]:::code
        Husky["Husky Pre-commit"]:::code
    end

    %% Connections
    Client -->|"HTTP Request"| Server
    ThirdParty -->|"HTTP Request"| Server
    Server --> MainRouter
    MainRouter --> AnnRoute
    MainRouter --> GenreRoute
    MainRouter --> InstRoute
    MainRouter --> TagRoute
    MainRouter --> StatesRoute
    MainRouter --> FormDataRoute

    AnnRoute --> AnnCtrl
    GenreRoute --> GenreCtrl
    InstRoute --> InstCtrl
    TagRoute --> TagCtrl
    StatesRoute --> StatesCtrl
    FormDataRoute --> FormDataCtrl

    AnnCtrl --> EmailService
    AnnCtrl --> S3Service
    AnnCtrl --> DBConfig
    GenreCtrl --> DBConfig
    InstCtrl --> DBConfig
    TagCtrl --> DBConfig
    StatesCtrl --> DBConfig
    FormDataCtrl --> DBConfig

    UploadMW --> S3Service

    DBConfig --> Postgres
    S3Service --> S3Bucket
    EmailService --> MailerSend
    EmailService --> EmailTpl
    DiscordSvc --> DiscordAPI

    GitPush --> GHActions
    GHActions --> DockerBuild
    DockerBuild --> Deploy
    GHActions --> Migrations
    GHActions --> Seed

    Utils --> Server
    Vitest --> TestAnn
    Vitest --> TestGenre
    Vitest --> TestInst
    Vitest --> TestTag
    Vitest --> TestStates

    %% Click Events
    click Server "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/server.js"
    click GHActions "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/.github/workflows/main.yml"
    click DockerBuild "https://github.com/muito-alem-do-microfone/bsb-api/tree/main/Dockerfile"
    click Migrations "https://github.com/muito-alem-do-microfone/bsb-api/tree/main/prisma/migrations/"
    click Seed "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/prisma/seed.js"
    click GHActions "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/prisma/schema.prisma"
    click DBConfig "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/config/db.config.js"
    click MainRouter "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/index.js"
    click AnnRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/announcement.routes.js"
    click GenreRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/genre.routes.js"
    click InstRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/instrument.routes.js"
    click TagRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/tag.routes.js"
    click StatesRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/states.routes.js"
    click FormDataRoute "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/routes/formData.routes.js"
    click CtrlIndex "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/index.js"
    click AnnCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/announcement.controller.js"
    click GenreCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/genre.controller.js"
    click InstCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/instrument.controller.js"
    click TagCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/tag.controller.js"
    click StatesCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/states.controller.js"
    click FormDataCtrl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/controllers/formData.controller.js"
    click UploadMW "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/middlewares/upload.js"
    click S3Service "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/services/s3/imageUpload.js"
    click EmailService "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/services/email/sendEmail.js"
    click EmailTpl "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/services/email/templates/announcementConfirmation.js"
    click Utils "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/utils/index.js"
    click Vitest "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/vitest.config.js"
    click TestAnn "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/test/announcement.test.js"
    click TestGenre "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/test/genre.test.js"
    click TestInst "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/test/instrument.test.js"
    click TestTag "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/test/tag.test.js"
    click TestStates "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/src/test/states.test.js"
    click Package "https://github.com/muito-alem-do-microfone/bsb-api/blob/main/package.json"
    click Husky "https://github.com/muito-alem-do-microfone/bsb-api/tree/main/.husky/pre-commit"

    %% Styles
    classDef code fill:#D6E9F8,stroke:#4A90E2,color:#0B2E6F
    classDef service fill:#E6F8E6,stroke:#34A853,color:#0F5132
    classDef external fill:#FFF4E5,stroke:#FB8C00,color:#663C00
    classDef db fill:#F0E6FF,stroke:#9C27B0,color:#4A0837
```
