How muito-alem-do-microfone/bsb-api works
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