How geocoderdev/siasis-api01-dev works
Project type and purpose
• This is a backend REST-style API (“API01-SIASIS”) written in Node.js/TypeScript.
• It serves attendance, user management and related endpoints for multiple SIASIS roles (auxiliar, directivo, profesor, responsable, etc.).
• It runs on Vercel/Serverless or a Node.js host, uses Prisma + raw SQL for PostgreSQL, Redis for caching or session/OTP data, and integrates with GitHub EMCS01 and Google Drive for file backups.
File structure
Top-level directories:
• prisma – database schema + migrations (PostgreSQL via Prisma).
• core – “domain” folder containing:
– databases/config (Prisma, Redis clients)
– connectors/postgres.ts (DB connection)
– queries/RDP02 (raw SQL queries organized by domain)
– external (adapters for GitHub EMCS01, Google Drive).
• src – application code:
– app.ts (Express or similar HTTP server setup)
– routes/api (route modules per resource)
– middlewares (auth by role, SQL-injection prevention, param checks)
– lib/helpers (business logic: JWT, encryption, validation, OTP email, file uploads, error handlers)
– constants & interfaces (shared types, enums, environment configs).
• .github/workflows – CI/CD pipelines for development, certification, production.
Architecture insights from README & structure
• Layered/hexagonal architecture separating HTTP layer (routes + middlewares), business logic (lib/helpers), data access (core/databases), and external integrations (core/external).
• Uses Prisma ORM alongside raw SQL for complex queries.
• JWT-based authentication per role with cookies.
• Redis for caching or short-lived data (OTP codes).
• External adapters follow an adapter pattern under core/external.
a. Main components:
• Clients (Web/Mobile)
• API Gateway / Load Balancer (Vercel or Nginx)
• API Server (Node.js/Express)
– HTTP Layer: Routes & Middlewares
– Service Layer: lib/helpers (JWT, encryption, email, validators)
– Domain/Data Layer: core/databases (Prisma client, Redis client, raw SQL queries)
• Data Stores: PostgreSQL, Redis
• External Services:
– GitHub EMCS01 API
– Google Drive API
• CI/CD: GitHub Actions
• Deployment: Vercel (or container host)
b. Relationships & interactions:
1. Client → Load Balancer → API Server
2. API Server: request passes through Middlewares → Route Handler → Business Logic → Data Connectors → PostgreSQL/Redis or External Adapters → back up the chain to client.
3. Background jobs or hooks may call Google Drive adapter for file backup and GitHub EMCS01 adapter for external data.
c. Architectural patterns/design principles:
– Layered architecture with clear separation of concerns
– Repository/Connector pattern for data access
– Adapter pattern for external services
– DRY and modular helpers for cross-cutting concerns (auth, validation, error handling)
d. Key technologies/frameworks:
– Node.js + Express (or similar) for HTTP server
– TypeScript for strong typing
– Prisma ORM + raw SQL for PostgreSQL
– Redis client for caching/OTP
– JWT for authentication
– GitHub Actions for CI/CD
– Vercel (serverless) or container for deployment
• HTTP/API Layer (blue)
• Business Logic (green)
• Data Access (orange)
• External Services (gray)
• Infrastructure/CI-CD (purple)