Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LMendoza70/SSA/llms.txt

Use this file to discover all available pages before exploring further.

The SSA Health Platform is cloud-ready from the first commit. The deployment strategy is intentionally progressive: early development and internal reviews run on simple, zero-maintenance PaaS providers (Render, Railway, Vercel) that deploy automatically from GitHub pushes, while the production path targets institutional infrastructure or managed cloud services on AWS, Azure, or Google Cloud. This means the team can validate the full system end-to-end in minutes without touching a server, and then migrate to hardened production infrastructure when the platform is ready for public launch without changing a line of application code.

​
Deployment Targets

For early development, feature branches, and internal testing:
  • Backend: Render or Railway — both support automatic deploys from a connected GitHub branch, zero-config TLS, and environment variable management through a web dashboard.
  • Frontend: Vercel — automatic preview deployments per pull request from the Vite build output.
  • Database: Render PostgreSQL or Supabase — both provide managed PostgreSQL with connection pooling and support for the pgvector extension required by the chatbot module.
  • Storage: Local filesystem (default) or Cloudflare R2 for zero-egress-fee object storage during early testing.

​
Environment Variables Reference

The backend reads all runtime configuration from environment variables. Never commit secrets to the repository. Use your hosting provider’s secrets manager or a .env.production file that is excluded from version control.
backend/.env.production
# ── Database ────────────────────────────────────────────────────────────────
DATABASE_URL=postgresql://user:password@host:5432/ssa_production

# ── Authentication ───────────────────────────────────────────────────────────
JWT_SECRET=<strong-random-secret-min-64-chars>
JWT_REFRESH_SECRET=<different-strong-random-secret>
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# ── Storage ──────────────────────────────────────────────────────────────────
STORAGE_DRIVER=s3
STORAGE_S3_BUCKET=ssa-media-production
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ACCESS_KEY=...
STORAGE_S3_SECRET_KEY=...

# ── AI / Chatbot ─────────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_CHAT_MODEL=gpt-4o
CHATBOT_SIMILARITY_THRESHOLD=0.75

# ── Social Media ─────────────────────────────────────────────────────────────
FACEBOOK_PAGE_ID=...
FACEBOOK_ACCESS_TOKEN=...
# (add tokens for Instagram, X, TikTok, YouTube as each adapter is enabled)

# ── Application ──────────────────────────────────────────────────────────────
PORT=3000
NODE_ENV=production
FRONTEND_URL=https://ssa.gob.mx
CORS_ORIGINS=https://ssa.gob.mx,https://admin.ssa.gob.mx
JWT_SECRET and JWT_REFRESH_SECRET must be different values. Using the same secret for both token types eliminates the security boundary between access and refresh tokens. Generate each independently with openssl rand -base64 64.

​
Database Setup

Run these steps once when provisioning a new environment. For subsequent deployments, only the migration step is needed.
1

Create the database

Connect to your PostgreSQL instance as a superuser and create the production database. The pgvector extension must be enabled in the same database that Prisma will use.
CREATE DATABASE ssa_production;
\c ssa_production;
CREATE EXTENSION IF NOT EXISTS vector;
2

Run migrations

Prisma’s migrate deploy command applies all pending migrations in order without prompting. It is safe to run on a live database — each migration runs inside a transaction.
cd backend
DATABASE_URL=postgresql://user:password@host:5432/ssa_production \
  npx prisma migrate deploy
3

Seed initial data (first deploy only)

The seed script creates the default admin user, system roles, and any required lookup data. Only run this on the very first deployment of a fresh database.
DATABASE_URL=postgresql://user:password@host:5432/ssa_production \
  npx prisma db seed
Running the seed script against an already-populated database may create duplicate records or overwrite existing configuration. Guard the seed command behind a one-time flag or a manual runbook step.

​
Build and Start

# Install production dependencies only
npm ci --omit=dev

# Compile TypeScript
npm run build

# Start the production server
NODE_ENV=production npm run start:prod
On PaaS providers like Render and Railway, the build and start commands are configured in the dashboard or a render.yaml / railway.toml file. The commands above are identical — the platform handles the execution environment.

​
Docker

The platform ships with a Dockerfile and docker-compose.yml for containerised deployments. This is the recommended path for institutional servers and any environment where you want a reproducible, isolated runtime. 
# Build and start all services (backend + postgres)
docker compose up --build -d

# Run migrations inside the running backend container
docker compose exec backend npx prisma migrate deploy

# View backend logs
docker compose logs -f backend
The docker-compose.yml defines three services: postgres (PostgreSQL with pgvector), backend (NestJS), and optionally nginx (reverse proxy with TLS). The backend service reads all configuration from environment variables, which can be injected via a .env file or your container orchestrator’s secrets store.

​
Health Check

The backend exposes a dedicated health check endpoint that probes all critical dependencies. Use this endpoint for load balancer health checks, uptime monitors, and container readiness probes. 
GET /health
Response when all systems are operational: 
{
  "status": "ok",
  "database": "up",
  "storage": "up"
}
If any dependency is unreachable, the endpoint returns HTTP 503 with the affected service marked as "down": 
{
  "status": "error",
  "database": "down",
  "storage": "up"
}

​
Production Checklist

Complete every item on this checklist before promoting any build to production. Share it with whoever performs the deployment — not just the original developer.
Security
  • All environment variables are set and contain no development defaults
  • JWT_SECRET and JWT_REFRESH_SECRET are strong (≥ 64 chars), unique, and different from each other
  • NODE_ENV=production is explicitly set
  • CORS origins (CORS_ORIGINS) are restricted to production domains only
  • Swagger UI is disabled or protected behind authentication in production
  • Storage bucket is not publicly writable; IAM permissions are scoped to the application role only
Database
  • pgvector extension is enabled on the production database
  • All Prisma migrations have been tested against a staging environment that mirrors production
  • Database backups are scheduled and the restore process has been tested
  • The database is not directly reachable from the public internet (use a VPC or firewall rule)
Application
  • The frontend VITE_API_URL points to the production backend base URL
  • Social media adapter tokens are valid and have the required scopes for publishing
  • OPENAI_API_KEY has spending limits configured in the OpenAI dashboard
  • The health check endpoint (GET /health) returns 200 ok after deployment
Operations
  • Monitoring and alerting are configured (uptime checks, error rate thresholds)
  • Application logs are being collected and retained (not just written to stdout and lost)
  • A rollback plan is documented and the previous image or build artifact is retained

Tech Stack

Library choices, versions, and rationale for the full platform stack.

Testing Strategy

How the CI pipeline runs unit and integration tests before every deployment.

API Conventions

REST endpoint patterns, authentication, and Swagger documentation setup.

Architecture Overview

Modular monolith structure, layers, and the design principles behind them.

Build docs developers (and LLMs) love

Get started for freeTalk to us