Infrastructure Truth Map
Purpose: Single source of truth for Fulcrum infrastructure state
Audience: Operators, DevOps, Backend Engineers
Verify: scripts/validate-infra.sh
Document Governance
This document follows the rules in DOC_GOVERNANCE.md:
- Every claim must have evidence
- IS section contains verified facts only
- SHOULD section contains intended architecture (ADR-backed)
Source of Truth Hierarchy: ADR → This Document → Code behavior
Section A: Truth Map — IS (Verified State)
Facts proven by code reference, script output, or manual verification.
A.1 Railway Services
| Claim |
Status |
Proof |
Owner |
Last Verified |
| 6 active Railway services |
VERIFIED |
Railway MCP list_services |
Ops |
2026-01-31 |
| fulcrum-server serves API + MCP |
VERIFIED |
cmd/fulcrum-server/main.go:437 |
Backend |
2026-01-31 |
| event-processor consumes NATS |
VERIFIED |
cmd/event-processor/main.go |
Backend |
2026-01-31 |
| timescaledb-docker is PostgreSQL 16 |
VERIFIED |
Railway service config |
Ops |
2026-01-31 |
| Redis active as cache layer |
VERIFIED |
Railway MCP |
Ops |
2026-01-31 |
| NATS active for JetStream |
VERIFIED |
Railway MCP |
Ops |
2026-01-31 |
| fulcrum-mcp service deleted |
VERIFIED |
Railway MCP (not in list) |
Ops |
2026-01-31 |
Service Details
| Service |
Internal Domain |
Purpose |
| fulcrum-server |
fulcrum-server.railway.internal |
Main API + MCP endpoint |
| event-processor |
event-processor.railway.internal |
NATS event consumer |
| dashboard |
dashboard.railway.internal |
Admin UI build artifact |
| timescaledb-docker |
timescaledb-docker.railway.internal:5432 |
PostgreSQL 16 + TimescaleDB |
| Redis |
redis.railway.internal:6379 |
Cache layer |
| nats |
nats.railway.internal:4222 |
JetStream messaging |
A.2 Database
| Claim |
Status |
Proof |
Owner |
Last Verified |
| Single database: timescaledb-docker |
VERIFIED |
Railway MCP |
Ops |
2026-01-31 |
| Database name: fulcrum_metrics |
VERIFIED |
POSTGRES_CONN_STR env var |
Ops |
2026-01-31 |
Schema fulcrum for app tables |
VERIFIED |
infra/migrations/postgres/ |
Backend |
2026-01-31 |
Schema metrics for telemetry |
VERIFIED |
infra/migrations/postgres/ |
Backend |
2026-01-31 |
| RLS enabled on app tables |
VERIFIED |
000002_enable_rls.up.sql |
Backend |
2026-01-31 |
| 24 up migrations exist |
VERIFIED |
ls infra/migrations/postgres/*.up.sql |
Backend |
2026-01-31 |
Database Connection
Host: timescaledb-docker.railway.internal
Port: 5432
Database: fulcrum_metrics
User: fulcrum
A.3 Domains
| Claim |
Status |
Proof |
Owner |
Last Verified |
| fulcrumlayer.io → Vercel |
VERIFIED |
curl -I returns Vercel headers |
Ops |
2026-01-31 |
| api.fulcrumlayer.io → Railway |
VERIFIED |
curl health returns fulcrum-server |
Ops |
2026-01-31 |
| docs.fulcrumlayer.io → GitHub Pages |
VERIFIED |
curl -I |
Ops |
2026-01-31 |
A.4 MCP Architecture
| Claim |
Status |
Proof |
Owner |
Last Verified |
| MCP endpoint: POST /mcp |
VERIFIED |
cmd/fulcrum-server/main.go:437-438 |
Backend |
2026-01-31 |
| MCP health: GET /mcp/health |
VERIFIED |
curl api.fulcrumlayer.io/mcp/health |
Ops |
2026-01-31 |
| Auth: Clerk JWT or X-API-Key |
VERIFIED |
internal/gateway/middleware.go |
Backend |
2026-01-31 |
| No standalone MCP service |
VERIFIED |
Railway MCP (fulcrum-mcp not in list) |
Ops |
2026-01-31 |
Canonical Endpoint: POST https://api.fulcrumlayer.io/mcp
A.5 Environment Variables
fulcrum-server
| Variable |
Value Pattern |
Status |
Proof |
| DATABASE_URL |
timescaledb-docker.railway.internal |
VERIFIED |
Railway env |
| REDIS_URL |
redis.railway.internal:6379 |
VERIFIED |
Railway env |
| NATS_URL |
nats://nats.railway.internal:4222 |
VERIFIED |
Railway env |
| CLERK_SECRET_KEY |
(from Doppler) |
VERIFIED |
Doppler prd config |
event-processor
| Variable |
Value Pattern |
Status |
Proof |
| POSTGRES_CONN_STR |
timescaledb-docker (fulcrum schema) |
VERIFIED |
Railway env |
| POSTGRES_CONN_STR_METRICS |
timescaledb-docker (metrics schema) |
VERIFIED |
Railway env |
| NATS_URL |
nats://nats.railway.internal:4222 |
VERIFIED |
Railway env |
| REDIS_ADDR |
redis.railway.internal:6379 |
VERIFIED |
Railway env |
Stale Variables (Tech Debt)
| Variable |
Status |
Notes |
| POSTGRES_HOST=timescaledb |
UNUSED |
Superseded by POSTGRES_CONN_STR |
| POSTGRES_USER=postgres |
UNUSED |
Credentials in connection string |
| DATABASE_URL=${Postgres.DATABASE_URL} |
UNUSED |
Unresolved reference |
A.6 Volumes
| Volume |
Service |
Mount Path |
Status |
Proof |
| redis-volume |
Redis |
/data |
VERIFIED |
Railway MCP |
| timescaledb-docker-volume |
timescaledb-docker |
/var/lib/postgresql/data |
VERIFIED |
Railway MCP |
| fulcrum-server-volume |
nats |
/data |
VERIFIED |
Railway MCP |
A.7 Health Endpoints
| Endpoint |
Expected Response |
Status |
Proof |
| https://api.fulcrumlayer.io/health |
{"service":"fulcrum-server","status":"healthy"} |
VERIFIED |
curl |
| https://api.fulcrumlayer.io/mcp/health |
{"service":"fulcrum-mcp","status":"healthy"} |
VERIFIED |
curl |
| https://fulcrumlayer.io |
HTTP 200 |
VERIFIED |
curl |
Section B: Truth Map — SHOULD (Intended Contract)
The intended stable architecture. Does NOT include roadmap or promises.
B.1 Domain Architecture (Intended)
| Domain |
Owner |
Target |
Purpose |
fulcrumlayer.io |
Vercel |
Dashboard app |
Primary user interface |
www.fulcrumlayer.io |
Vercel |
Redirect to apex |
SEO |
api.fulcrumlayer.io |
Railway |
fulcrum-server |
Canonical API endpoint |
docs.fulcrumlayer.io |
GitHub Pages |
Documentation |
Public docs |
mcp.fulcrumlayer.io |
Railway |
fulcrum-server |
Optional alias - prefer api.fulcrumlayer.io/mcp |
B.2 Service Architecture (Intended)
| Service |
Type |
Purpose |
Dependencies |
| fulcrum-server |
Go binary |
API + MCP + Gateway |
timescaledb-docker, Redis, nats |
| event-processor |
Go binary |
Event processing |
timescaledb-docker, nats, Redis |
| dashboard |
Next.js |
Admin UI |
fulcrum-server API |
| timescaledb-docker |
PostgreSQL 16 |
Persistence |
None |
| Redis |
Cache |
Policy cache, sessions |
None |
| nats |
JetStream |
Event streaming |
None |
B.3 Configuration Hierarchy (Intended)
When environment variables conflict:
- Doppler (prd config) - Master secrets store
- Change here first, then sync to platforms
- Railway - Runtime service configuration
- References Doppler secrets where possible
- Vercel - Dashboard-specific variables
- NEXT_PUBLIC_* variables only
Rule: Never change Railway/Vercel env vars directly without updating Doppler first.
B.4 Migration Policy (Intended)
| Claim |
Source |
| Migrations run automatically on container start via migrate.sh |
infra/docker/Dockerfile.server CMD |
migrate.sh converts connection strings and runs migrate up |
infra/docker/Dockerfile.server (embedded script) |
| Down migrations optional for destructive changes |
Convention |
Section C: Deprecated / Forbidden
Items that should NOT exist or be recreated.
| Item |
Status |
Reason |
Date |
fulcrum-mcp Railway service |
DELETED |
MCP merged into fulcrum-server |
2026-01-31 |
mcp.fulcrumlayer.io as canonical |
DEPRECATED |
Use api.fulcrumlayer.io/mcp |
2026-01-31 |
| Legacy TimescaleDB service name (pre-docker) |
RENAMED |
Use timescaledb-docker |
2026-01-31 |
| Legacy TimescaleDB DB service name (pre-docker) |
RENAMED |
Use timescaledb-docker |
2026-01-31 |
Verification
Automated
# Run full infrastructure verification
./scripts/validate-infra.sh
# Output saved to:
# docs/infra/validate-infra.latest.txt
Manual Verification Required
| Item |
Procedure |
Frequency |
| Autodeploy disabled |
Railway dashboard → Service → Settings |
Weekly |
| Doppler sync status |
Doppler dashboard → prd config |
Weekly |
| Vercel deployment status |
Vercel dashboard |
Weekly |
Document created: 2026-02-01
Merged from: PROD_TRUTH_MAP.md, PLATFORM_TRUTH_MAP.md
Last verified: 2026-01-31