Web API

Overview

The web-api is the primary API backend for the Rapida dashboard. Every request from the browser — authentication, organization setup, assistant management, credential storage — goes through this service. It also acts as the gRPC proxy for downstream services, validating JWT tokens before forwarding requests.

Port

9001 — HTTP · gRPC · gRPC-web (cmux)

Language

Go 1.25 Gin (REST) + gRPC

Storage

PostgreSQL web_db Redis (session cache)

All gRPC-web requests from the browser, except for real-time audio, are routed through web-api. The service validates the JWT and proxies the request to the correct downstream service using typed gRPC clients from pkg/clients/.

Components

Authentication & Session Management

Handles user registration, login, password recovery, OAuth 2.0 flows, and JWT issuance.

Feature	Detail
Token type	JWT (signed with `SECRET`, shared across all services)
Token storage	Client-side (Authorization header)
Session cache	Redis DB 1
OAuth providers	Google, GitHub, Microsoft (configured per deployment)
Token expiry	Configurable; default 24 hours

Organization & Project Hierarchy

Every resource in Rapida is scoped to an Organization → Project hierarchy. The web-api enforces this scoping at the gRPC interceptor level.

Organization
└── Project
    ├── Assistants
    ├── Knowledge Bases
    ├── Integrations
    └── Webhooks

Each entity stores organization_id and project_id via the Organizational base model. The gRPC auth interceptor rejects any request where the JWT’s organization claim does not match the target resource.

Credential Vault

Provider API keys and OAuth tokens are encrypted with AES-256 before storage. The encryption key is derived from SECRET. The vault is the source of truth for all provider credentials — integration-api reads from it at call time.

Operation	Behavior
Store key	AES-256-GCM encrypt → write to `web_db`
Retrieve key	Read from `web_db` → decrypt in-memory → forward to `integration-api`
Rotate key	Replace ciphertext; existing calls in flight are unaffected
Audit	Every vault read/write is logged with user ID and timestamp

Internal gRPC Proxy

The web-api acts as a proxy for all dashboard gRPC calls. It validates the JWT, extracts the organization context, and forwards to the correct downstream service.

gRPC Path Prefix	Forwarded To
`/web_api`	Local (web-api owns this)
`/vault_api`	Local (web-api owns this)
`/workflow_api` · `/assistant_api`	`assistant-api:9007`
`/knowledge_api`	`assistant-api:9007`
`/tool_api` · `/endpoint_api` · `/webhook_api`	`endpoint-api:9005`
`/provider_api` · `/integration_api`	`integration-api:9004`
`/connect_api`	Local (OAuth connector)
`/document_api`	`document-api:9010`
`/lead_api`	Local

Entity and Data Model

All entities compose base GORM models:

Base Model	Fields
`Audited`	`id` (Snowflake), `created_at`, `updated_at`
`Mutable`	`status`, `created_by`, `updated_by`
`Organizational`	`project_id`, `organization_id`

IDs are generated as Snowflake IDs in the BeforeCreate GORM hook — no UUID dependency. The Snowflake generator is initialized at service startup using the service instance ID.

Request Flow

Configuration

Edit docker/web-api/.web.env before starting the service.

Required variables

Variable	Required	Default	Description
`SECRET`	✅ Yes	`rpd_pks`	JWT signing secret — must match all services
`POSTGRES__HOST`	✅ Yes	`postgres`	PostgreSQL host
`POSTGRES__DB_NAME`	✅ Yes	`web_db`	Database name
`POSTGRES__AUTH__USER`	✅ Yes	`rapida_user`	Database user
`POSTGRES__AUTH__PASSWORD`	✅ Yes	—	Database password
`REDIS__HOST`	✅ Yes	`redis`	Redis host
`INTEGRATION_HOST`	✅ Yes	`integration-api:9004`	integration-api gRPC address
`ENDPOINT_HOST`	✅ Yes	`endpoint-api:9005`	endpoint-api gRPC address
`ASSISTANT_HOST`	✅ Yes	`assistant-api:9007`	assistant-api gRPC address
`DOCUMENT_HOST`	✅ Yes	`http://document-api:9010`	document-api HTTP address

Tuning variables

Variable	Default	Description
`LOG_LEVEL`	`debug`	`debug` · `info` · `warn` · `error`
`ENV`	`development`	`development` · `staging` · `production`
`POSTGRES__MAX_OPEN_CONNECTION`	`10`	Database connection pool size
`POSTGRES__MAX_IDEAL_CONNECTION`	`10`	Idle connections to keep open
`REDIS__MAX_CONNECTION`	`5`	Redis connection pool size
`ASSET_STORE__STORAGE_TYPE`	`local`	`local` · `s3` · `azure`

Full environment file

# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=web-api
HOST=0.0.0.0
PORT=9001
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__PORT=5432
POSTGRES__DB_NAME=web_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__MAX_OPEN_CONNECTION=10
POSTGRES__MAX_IDEAL_CONNECTION=10
POSTGRES__SSL_MODE=disable

# ── Redis (second-level GORM cache) ───────────────────────────────
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__DB=1
POSTGRES__SLC_CACHE__MAX_CONNECTION=10

# ── Redis ─────────────────────────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=5

# ── Asset storage ─────────────────────────────────────────────────
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/web

# ── Internal service addresses ────────────────────────────────────
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
DOCUMENT_HOST=http://document-api:9010
UI_HOST=https://localhost:3000

SECRET is used for JWT signing and credential vault encryption. All services must share the same value. Changing it in production will invalidate all active sessions and make stored vault credentials unreadable. Rotate carefully.

Running

Docker Compose
From Source

# Start web-api and its dependencies
make up-web

# Follow logs
make logs-web

# Rebuild after code changes (no cache)
make rebuild-web

# Open a shell in the container
make shell-web

Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.

# Load base env file
export $(grep -v '^#' docker/web-api/.web.env | xargs)

# Override Docker hostnames
export POSTGRES__HOST=localhost
export REDIS__HOST=localhost
export INTEGRATION_HOST=localhost:9004
export ENDPOINT_HOST=localhost:9005
export ASSISTANT_HOST=localhost:9007
export DOCUMENT_HOST=http://localhost:9010

# Run
go run cmd/web/web.go

Database Migrations

Migrations run automatically at service startup using golang-migrate. Migration files are in api/web-api/migrations/ and follow sequential naming:

000001_initial_schema.up.sql
000001_initial_schema.down.sql
000002_add_oauth_tokens.up.sql

To run manually during local development:

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

migrate \
  -path api/web-api/migrations \
  -database "postgresql://rapida_user:rapida_db_password@localhost:5432/web_db?sslmode=disable" \
  up

Health & Observability

Endpoint	Purpose
`GET /readiness/`	Reports whether the service is ready (DB + Redis connected)
`GET /healthz/`	Liveness probe

curl http://localhost:9001/readiness/

Troubleshooting

Service exits immediately on startup

The most common cause is PostgreSQL not yet healthy. Check make logs-web and confirm the postgres container is Up (healthy).

docker compose ps postgres
make logs-web | head -40

JWT validation fails across services

All services must share the same SECRET value. Confirm it is identical in .web.env, .assistant.env, .integration.env, and .endpoint.env.

OAuth login redirects fail

gRPC proxy returns 'service unavailable'

The target downstream service must be running and healthy.
Verify INTEGRATION_HOST, ENDPOINT_HOST, ASSISTANT_HOST point to reachable addresses.
Check make status to confirm all containers are Up.

Next Steps

Assistant API

Voice orchestration service that web-api proxies to.

Integration API

Provider credentials used by the vault.

Installation Guide

Deploy the full platform with Docker Compose.

Architecture

Full system topology and routing.

Getting Started

Dashboard (UI)

Assistant API

Integration API

Endpoint API

Document API

Web API

Overview

Port

Language

Storage

Components

Request Flow

Configuration

Required variables

Tuning variables

Full environment file

Running

Database Migrations

Health & Observability

Troubleshooting

Next Steps

Assistant API

Integration API

Installation Guide

Architecture

Getting Started

Dashboard (UI)

Web API

Assistant API

Integration API

Endpoint API

Document API

​Overview

Port

Language

Storage

​Components

​Request Flow

​Configuration

​Required variables

​Tuning variables

​Full environment file

​Running

​Database Migrations

​Health & Observability

​Troubleshooting

​Next Steps

Assistant API

Integration API

Installation Guide

Architecture

Overview

Components

Request Flow

Configuration

Required variables

Tuning variables

Full environment file

Running

Database Migrations

Health & Observability

Troubleshooting

Next Steps