Getting Started

Developer setup guide for running all Prism services locally.

Updated Apr 3, 2026

Prerequisites

Tool	Version	Purpose
Node.js	20+	Frontend dev server and tooling
npm	10+	Frontend package management
Go	1.22+	Backend API compilation
PostgreSQL	15+ (with PostGIS)	Database (or use Supabase/Docker)
Redis	7+	Cache (or use Upstash/Docker)
Docker + Compose	Latest	Full-stack local development
Git	2.40+	Version control

Optional:

k6 — for load testing (make load-smoke)
swag CLI — for regenerating Swagger docs (make api-docs)

Repository Structure

project-prism/
├── frontend/           # Vite + React + TypeScript SPA
├── go-backend/         # Go REST API service
│   ├── cmd/api/        # API entry point
│   ├── cmd/import_worker/  # Async import worker
│   ├── internal/       # Application code (handler/service/repo/domain)
│   ├── pkg/            # Shared packages (apierror, response)
│   ├── ops/            # Docker Compose + monitoring configs
│   ├── perf/           # k6 load test scripts
│   └── docs/           # Generated Swagger/OpenAPI specs
├── database/           # Canonical SQL schema + migrations
├── docs/               # Developer documentation (this site)
├── docs-site/          # User-facing documentation (Fumadocs/Next.js)
├── marketing/          # Public marketing site (Next.js)
├── supabase/           # Legacy Supabase artifacts
└── test-data/          # Sample data for development

Quick Start: Frontend

cd frontend
cp .env.example .env
npm install
npm run dev

The dev server starts at http://localhost:5173.

Required Environment Variables

Variable	Description
`VITE_API_BASE_URL`	Backend API URL (e.g., `http://localhost:8080`)
`VITE_CLERK_PUBLISHABLE_KEY`	Clerk publishable key for auth

Optional Environment Variables

Variable	Description
`VITE_CLERK_PROXY_URL`	Clerk proxy URL (production only)
`VITE_MAP_3D_STYLE_URL`	MapLibre 3D style URL for 3D map toggle
`VITE_SENTRY_DSN`	Sentry DSN for error tracking

Frontend Commands

Command	Purpose
`npm run dev`	Start dev server
`npm run build`	Production build
`npm run typecheck`	TypeScript type checking
`npm run lint`	ESLint
`npm run test`	Vitest unit/component tests
`npm run test:e2e`	Playwright end-to-end tests

Quick Start: Backend

cd go-backend
cp .env.example .env
go mod download
make run

The API server starts at http://localhost:8080.

Required Environment Variables

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`CLERK_SECRET_KEY`	Clerk secret key for JWT validation
`CLERK_JWKS_URL`	Clerk JWKS endpoint URL
`CLERK_ISSUER`	Expected JWT issuer

Optional Environment Variables

Variable	Default	Description
`PORT`	`8080`	HTTP listen port
`ENV`	`development`	Environment (`development`, `staging`, `production`)
`LOG_LEVEL`	`info`	Log level (`debug`, `info`, `warn`, `error`)
`ALLOWED_ORIGINS`	`*`	CORS allowed origins (comma-separated)
`CLERK_AUDIENCE`	—	Expected JWT audience
`STRICT_CLERK_SCOPES`	`false`	Strict scope enforcement (must be `true` in production)
`TRUST_CLOUDFLARE_HEADERS`	`false`	Trust Cloudflare real-IP headers
`RATE_LIMIT_PER_SECOND`	—	Rate limit requests per second
`RATE_LIMIT_BURST`	—	Rate limit burst size
`METRICS_SCRAPE_TOKEN`	—	Bearer token for `/metrics` endpoint protection
`SENTRY_DSN`	—	Sentry DSN for error tracking

Backend Make Commands

Command	Purpose
`make run`	Start API server
`make dev`	Start with hot reload
`make test`	Run all tests
`make test-coverage`	Run tests with coverage report
`make build`	Compile binary
`make fmt`	Format Go code
`make lint`	Run Go linter
`make api-docs`	Regenerate Swagger/OpenAPI specs
`make api-docs-check`	Check Swagger docs are up-to-date (CI)
`make load-smoke`	Run k6 smoke test
`make clean`	Remove build artifacts

Quick Start: Full Stack (Docker)

Run backend + Postgres + Redis + monitoring stack:

cd go-backend/ops
cp .env.example .env
# Edit .env with your Slack webhook URLs for alerting
docker compose up --build -d

Local Service Endpoints

Service	URL
Backend API	`http://localhost:8080`
Health Check	`http://localhost:8080/health`
Readiness Check	`http://localhost:8080/ready`
Metrics	`http://localhost:8080/metrics`
Swagger UI	`http://localhost:8080/swagger/index.html`
Prometheus	`http://localhost:9090`
Alertmanager	`http://localhost:9093`
Grafana	`http://localhost:3000`

Database Setup

Option A: Use Managed Supabase

Point DATABASE_URL at your Supabase Postgres instance. PostGIS is pre-installed.

Option B: Local Docker (via Compose)

The go-backend/ops/docker-compose.yml includes a Postgres + PostGIS container.

Option C: Local PostgreSQL

# Create database
createdb prism

# Enable PostGIS
psql prism -c "CREATE EXTENSION IF NOT EXISTS postgis;"

# Apply schema
psql prism < database/PRISM_vNext_FINAL.sql

Schema Files

File	Purpose
`database/PRISM_vNext_FINAL.sql`	Full rebuild script (canonical schema)
`database/PRISM vNext.sql`	Historical duplicate (kept identical)
`database/migrations/`	Incremental migration files for existing databases

Clerk Authentication Setup

Create a Clerk application at clerk.com
Create an organization and configure org permissions
Set VITE_CLERK_PUBLISHABLE_KEY in frontend/.env
Set CLERK_SECRET_KEY, CLERK_JWKS_URL, CLERK_ISSUER in go-backend/.env
Configure org permissions to match Prism's scope model (see docs/backend/account-profile-onboarding-guide.md)

Permission Scopes

The backend requires these Clerk org permissions (prefixed with org: in Clerk, normalized to plain form by backend):

Read scopes: buildings:read, comps:read, tims:read (tim:read in Clerk), tenants:read, owners:read, contacts:read, brokerage_firms:read, reports:read, building_parks:read, key_points:read

Write scopes: All read scopes plus *:write variants and export

Admin scopes: All write scopes plus api_keys:manage, audit:read, export:admin

CI/CD

GitHub Actions workflow: .github/workflows/go-backend-ci.yml

Triggers on PRs and pushes to qa + main branches (for backend/ops paths).

CI Checks

Check	Command
Go tests	`go test ./...`
Race detection	`go test -race ./internal/...`
Go vet	`go vet ./...`
Swagger drift	`make api-docs-check`
Docker compose	`docker compose config`

Branch Strategy

feature → qa → main (production)

Feature branches merge into qa
qa is validated, then promoted to main via PR
main deploys to production