Amara

Amara's backend is a Go modular monolith using Gin. Business modules live under internal/; shared HTTP, configuration, and logging code lives under internal/platform/. See backend module boundaries.

Run the API

Install Go 1.26.10 or newer, then run from the repository root:

go mod download
make run

The API defaults to :8080. Check liveness with:

curl http://localhost:8080/healthz
# {"status":"ok"}

The API connects to the Amara Supabase PostgreSQL instance at startup and fails fast when the database is unreachable. /health reports process liveness only. See the Supabase ADR for the connection and migration approach.

Docker Compose

Compose builds the backend image (the API and worker are two execution roles of one codebase) and the web client image. It also starts a local Judge0 demo stack with its own PostgreSQL and Redis; Amara data stays in Supabase. The Judge0 configuration uses local demo credentials and is not for production.

docker compose up --build

Host ports default to API_PORT=8080 and WEB_PORT=3000; set them in the shell environment when the defaults collide.

• API: http://localhost:8080/health
• Web: http://localhost:3000 (Next.js server with standalone runtime, proxying /v1 to the API, so browser traffic is same-origin)
• Worker: same image as the API

Secrets follow the single Infisical path used by the rest of the project: run Compose under the Infisical CLI with the backend folder — database credentials are required and Compose refuses to start without them:

infisical run --env=dev --path=/backend -- docker compose up

docker-compose.yml interpolates consuming variables from the injected environment (for example DATABASE_URL: ${DATABASE_URL}); a local .env file stays non-secret. Future provider integrations add their variables to the same environment block.

Database migrations

Schema lives in supabase/migrations/ and runs against the linked Supabase project (amara-dev) with the Supabase CLI. Epic schemas are accounts, cand, job, invw, and ana — the auth schema name is reserved by Supabase. See the ADR.

supabase login                      # once per machine
make db-push                        # apply supabase/migrations to amara-dev
supabase migration new <name>       # create the next migration file

supabase link was already run for this checkout; new checkouts need supabase link --project-ref=<ref> plus the database password. Do not apply schema changes through the dashboard SQL editor; they must exist as migration files in this repository.

Infisical

Infisical is the secrets manager. The CLI injects configuration and secrets as environment variables before starting the API; Go reads them once at startup. The API does not load .env files or require Infisical credentials in its code. See the official CLI setup and runtime injection example.

After installing the CLI, log in (select the US Region) and run the API. The committed .infisical.yaml links this checkout to the Amara project, so infisical init is only needed when creating a new project:

infisical login
make run-secrets

All API configuration and secrets live in the backend folder of the project's dev environment. The Makefile targets that folder by default; select another environment with:

make run-secrets INFISICAL_ENV=staging

For CI and deployment, authenticate a machine identity outside the application, provide its access token as INFISICAL_TOKEN, and pass the project explicitly:

make build
infisical run --projectId=YOUR_PROJECT_ID --env=prod --path=/backend -- ./bin/api

Use your actual project ID, environment slug, and folder. Set APP_ENV=production in the production environment. No project ID or credentials are preconfigured. Restart the API after changing injected values so it reads the new configuration.

Configuration

.env.example lists non-secret settings and development values. Defaults apply when a variable is absent; invalid values fail startup. An explicitly empty origin or proxy list disables that feature.

This is the beginning of the README. Read the rest at the original. Read the full README ↗