Recova Backend API (Go Fiber)

Main backend service for Recova, handling authentication, profiles, routines/check-ins, journaling, community features, educational content, AI Coach, and API observability.

Active runtime for this repository: Go + Fiber. Legacy runtime archive (Node/Express): README.md.

Table of Contents

• Service Scope
• Domain Modules
• Tech Stack
• Quick Start
• Environment Configuration
• Make Commands
• Testing and Quality Gates
• OpenAPI and API Docs
• Deployment Overview
• Repository Structure
• Documentation Map
• Quick Troubleshooting

Service Scope

This service handles:

• Google Login + JWT session flow (/api/v1/auth/*)
• User profiles, onboarding, and settings (/api/v1/users/*)
• Routine check-ins, relapse tracking, and activity statistics (/api/v1/routine/*)
• Personal journals (/api/v1/journals)
• Community posts, comments, replies, and likes (/api/v1/community*)
• Educational content and daily content (/api/v1/education, /api/v1/content/daily)
• AI Coach chat, summaries, onboarding analysis, and persona preferences (/api/v1/ai/*)
• Health checks, metrics, and OpenAPI runtime routes (/health/*, /metrics, /openapi.yaml, /docs/api)

Domain Modules

Active modules are located in internal/modules/:

• auth
• users
• routine
• journals
• community
• education
• content
• ai
• achievements

Runtime route inventory is automatically synchronized in: docs/generated/routes.md.

Tech Stack

Area	Technology
Language	Go 1.26.x (toolchain pinned in go.mod)
HTTP Framework	Fiber v3.4.x
Database	PostgreSQL
ORM	GORM
Migration	golang-migrate (SQL up/down)
API Contract	OpenAPI 3.1
API Docs UI	Scalar
Authentication	JWT + Google OAuth token verification
Metrics	Prometheus client
Build/Task Runner	Make
Container Runtime	Docker + Docker Compose

Quick Start

1) Prerequisites

• Go >= 1.26
• Make
• Git
• Docker + Docker Compose (required for local DB/container profile)

Check the baseline setup:

make preflight

2) Setup Environment

cp .env.example .env

Update the minimum required values:

• JWT_SECRET
• GOOGLE_CLIENT_ID
• AI_API_KEY
• DATABASE_URL

Default local configuration:

• PORT=3001
• API_PREFIX=/api/v1
• APP_ENV=local

3) Choose Local Runtime Profile

Option A - Native API + DB in Docker (recommended for development)

docker compose -f docker-compose.local.yml up -d db
make migrate-up
make seed
make run

Option B - Full Docker Compose (API + DB)

docker compose -f docker-compose.local.yml up -d --build
make migrate-up
make seed
docker compose -f docker-compose.local.yml logs -f api

4) Quick Verification

curl -fsS http://localhost:3001/health/live
curl -fsS http://localhost:3001/health/ready
curl -I http://localhost:3001/docs/api

Environment Configuration

Complete references are available in:

• docs/ENVIRONMENT.md
• .env.example

Main environment variable groups:

• Application: APP_NAME, APP_ENV, NODE_ENV, PORT, API_PREFIX, APP_URL, DOCS_URL
• Database: DATABASE_URL, DIRECT_DATABASE_URL, pooling, SSL mode
• Authentication: JWT_SECRET, token TTL, cookie policy, GOOGLE_CLIENT_ID
• AI: AI_PROVIDER, AI_MODEL, AI_API_KEY, fallback provider/model
• Security: CORS, rate limiting, request body limit
• Observability: log level, request ID header, health timeout

Notes:

• make run, make migrate-*, and make seed automatically load .env via scripts/with-env.sh
• Override the env file using: ENV_FILE=.env.production make run

Make Commands

All tasks are available in the Makefile. Core commands:

Development

• make preflight check tools and project structure baseline
• make hooks-install install git pre-commit hooks (.githooks/pre-commit)
• make fmt format Go code (gofmt -w .)
• make lint static checks (go vet ./...)
• make build build binary ./bin/recova-api
• make run run the local API

Database

• make migrate-up
• make migrate-down
• make migrate-status
• make migrate-check
• make migrate-force VERSION=<n>
• make seed

API Contract and Docs

• make openapi-generate
• make openapi-check
• make openapi-autogen
• make openapi-autogen-watch
• make openapi-autogen-install-hook
• make scalar-check
• make scalar-preview

Testing and Validation

• make test
• make test-integration
• make test-e2e
• make test-performance
• make coverage
• make release-validation
• make module-consistency-check
• make module-consistency-full-check
• make security-scan
• make compose-smoke

Deployment and Verification

• make compose-smoke smoke test container compose stack
• make release-validation run E2E and performance release validation

Testing and Quality Gates

Baseline checks before merge:

make fmt
make lint
make test
make test-integration
make openapi-check
make scalar-check
make module-consistency-check

For higher confidence before release:

make release-validation
make module-consistency-full-check

Detailed strategy: docs/OPERATIONS.md.

OpenAPI and API Docs

API contract source:

• api/openapi/openapi.yaml

Generated artifacts:

• docs/generated/openapi.yaml
• docs/generated/routes.md
• scalar.config.json (Scalar navigation + docs wiring)

Runtime endpoints:

• Raw OpenAPI: GET /openapi.yaml
• Scalar UI: GET /docs/api

Recommended workflow:

make openapi-generate
make openapi-check

Notes:

• make openapi-autogen-watch maintains .openapi-watch-files and regenerates artifacts on change.
• Runbook: docs/OPERATIONS.md.

Deployment Overview

Production Deployment (Standalone Docker Compose & SSH)

Main CI/CD workflows:

• .github/workflows/ci-pr.yml (Pull Request Quality Gate)
• .github/workflows/ci-cd.yml (Production Release & SSH Deploy)
• docker-compose.yml (Production Compose Orchestration)

Automated steps:

1. Execute comprehensive off-site quality gate & database integration tests with ephemeral PostgreSQL 17.
2. Build & push immutable container image to GHCR (ghcr.io/recova-app/backend-v2:<tag>).
3. Connect via Tailscale mesh and dispatch remote deployment via SSH.
4. On VPS: verify Neon database connectivity, execute pre-migration snapshot, apply schema migrations, and recreate container (docker compose up -d).
5. Multi-route post-deployment smoke verification (/health/live, /health/ready, /openapi.yaml, auth boundary) with automated rollback on failure.

Complete reference: docs/DEPLOYMENT.md and docs/OPERATIONS.md.

Repository Structure

.
├── api/                       # OpenAPI source
├── artifacts/                 # Test/deployment artifact outputs
├── cmd/                       # Application/tool entrypoints
├── docs/                      # Technical documentation
├── internal/                  # Application code (app, modules, platform, shared)
├── migrations/                # SQL migrations + seeds
├── scripts/                   # Dev/ops automation scripts
├── test/                      # Integration harness and validation scripts
├── tools/                     # Deployment and Nginx host configurations
├── docker-compose.local.yml   # Local runtime
├── docker-compose.yml         # Production compose runtime
├── Dockerfile                 # Production-style image build
├── scalar.config.json         # Scalar docs configuration
└── Makefile                   # Task runner

Documentation Map

Start here:

• docs/OVERVIEW.md

Authoritative technical documentation:

• Architecture: docs/ARCHITECTURE.md
• API Specification: docs/API.md
• Database Architecture: docs/DATABASE.md
• Environment Configuration: docs/ENVIRONMENT.md
• Domain Modules: docs/MODULES.md
• Operations & Testing: docs/OPERATIONS.md
• Architecture Decisions: docs/ADR.md

Quick Troubleshooting

• config error during startup: check required environment variables in .env and docs/ENVIRONMENT.md
• Missing migrate binary: scripts will automatically fallback to the Docker image migrate/migrate:v4.19.1 if Docker is available
• openapi-check failed: run make openapi-generate and commit changes inside docs/generated/*
• health/ready failed: check DB connectivity and migration status (make migrate-status, make migrate-check)