AppMecca API Reference¶
Welcome to the AppMecca API documentation. This guide covers the REST API that serves as the single data access layer for all AppMecca clients.
What is the AppMecca API?¶
The AppMecca API is a REST API running as a Docker container on the AppMecca Docker host pool, backed by PostgreSQL (the AppMecca database). It is deployed by the standard CodeBuild + agent pipeline, exactly like any other AppMecca application. Every client — the admin CLI, the usage CLI, the dashboard, the aegis SPAs, third-party integrations — accesses application state through this API.
Why a Container?¶
The API must be the most resilient thing in the stack. If it goes down, the CLIs are stranded — there is no alternative path to the data. Running it as a container on the same host pool as everything else means it uses the platform's own zero-downtime blue/green deploy path, the same health checks, and the same ALB routing, with a long-lived asyncpg pool and no cold starts.
Resilience comes from replication and recovery rather than from a serverless runtime: the api service runs with replicas: 3 (see the API's own appmecca.yaml), and appmecca api recover can rebuild and redeploy it by writing straight to PostgreSQL when the API itself is unreachable.
What Lives Where¶
| Data Store | What It Holds | Why |
|---|---|---|
| PostgreSQL (AppMecca DB) | All application state — apps, builds, deployments, the deploy_queue, env vars, domains, ports, agents, users, groups, locks |
Single source of truth, no sync, no staleness |
PostgreSQL (appmecca_logs DB) |
Unified log storage and container stats | High-volume, separate lifecycle from application state |
| Redis (ElastiCache) | Celery broker + result backend, rate-limit state, WebSocket tickets, pub/sub | Ephemeral coordination, never a source of truth |
| DynamoDB (Resource Index) | AWS resource tracking across environments, in us-east-2 |
Infrastructure tracking for the admin CLI and agent — the API never reads or writes it |
The deploy queue is PostgreSQL
The queue was a DynamoDB table historically. It is now the deploy_queue
table, written by db/repositories/queue.py and polled by the agent's
PGQueueClient. The DynamoDB App Registry table has been retired entirely.
Technology Stack¶
| Technology | Purpose |
|---|---|
| FastAPI | Web framework (async, Pydantic models, OpenAPI docs) |
| uvicorn | ASGI server — runs the app directly, no adapter layer |
| Docker | Packaging; deployed to the host pool by the agent |
| ALB | HTTPS endpoint, host-based routing to the reserved api.{env}.{domain} hostname |
| PostgreSQL | The AppMecca database (the environment's RDS instance) |
| asyncpg | Async PostgreSQL driver (request path) |
| psycopg2 | Sync PostgreSQL driver (Celery worker + Beat tasks, entrypoint migrations) |
| Celery + Redis | Background workers and the Beat schedule |
| Alembic | Database migrations (chain shipped in appmecca-common) |
| Pydantic Settings | Environment-variable configuration |
| slowapi | Per-IP and per-email rate limits on /api/auth/*; per-credential + per-IP on /api/users/me/git-repos/* (BUGS #1086) |
Quick Links¶
| Task | Page |
|---|---|
| Understand the architecture | Architecture Overview |
| See all database tables | Database Schema |
| Configure environment variables | Environment Variables |
| Deploy the API | Docker Deployment |
| View available endpoints | Health |
| Understand authentication | Authentication |
| Set up local development | Getting Started |
| Run the test suite | Testing |
Relationship to the Rest of the Platform¶
The API lives in its own repository, checked out as the appmecca-api/ submodule of the platform meta-repo. It has its own pyproject.toml, virtual environment, Makefile and test suite, and the admin CLI, tenant CLI and agent all sit in their own submodules.
It is not independent of appmecca-common — it installs that wheel (which provides the appmecca Python package) and imports from it at runtime:
| Imported module | Used for |
|---|---|
appmecca.db.migrate |
Running the alembic chain from the container entrypoint |
appmecca.deploy.hostname |
The one canonical service-hostname formula |
appmecca.db.tls |
Shared datastore-TLS policy |
appmecca.email.service |
SES send path |
appmecca.deploy.cloudfront, .discovery, .git_preflight, .ns_scan, .storage_entitlement |
Shared deploy-side helpers |
Because appmecca-common is not on PyPI, the CodeBuild build stages its wheel into the Docker build context; a container built without it crash-loops on ModuleNotFoundError: No module named 'appmecca'.
The API is the single data access layer: the agent writes deployment results and heartbeats straight to PostgreSQL, and every other client goes through HTTP.