Port Map & Services Overview

A quick-reference for every service and data store in the GospeLib platform. Bookmark this page — you'll come back to it.

Application Ports

Service	Port	Language	Framework	Purpose
Admin	3001	TypeScript	Next.js 15	Internal admin dashboard
Web	3002	TypeScript	Next.js 15	User-facing scripture reader

Backend Service Ports

All external API traffic enters through the Gateway at port 8080. No other service is exposed directly to clients.

Service	Port	Language	Framework	Purpose
Gateway	8080	Go 1.23	Chi v5	API gateway — JWT validation, rate limiting, reverse proxy
Content	8100	Python 3.12	FastAPI	Scripture graph queries (FalkorDB)
Auth	8200	Go 1.23	Chi v5	Clerk wrapper, user sync, JWT middleware
Billing	8300	Go 1.23	Chi v5	Stripe subscriptions, entitlements
AI	8400	Python 3.12	FastAPI	LLM passage explanation, study questions
Notifications	8500	Go 1.23	Chi v5	Push (APNs/FCM), email (Resend), Redis Streams

The Ingest service is a CLI tool (Python/Click), not an HTTP service — it has no port.

Data Store Ports

Store	Port	Image	Purpose
FalkorDB	6379	falkordb/falkordb:latest	Primary graph database — scripture content & relationships
PostgreSQL	5432	pgvector/pgvector:pg16	Users, subscriptions, notes, AI embeddings (pgvector)
Redis	6380	redis:7-alpine	Cache, rate limiting, sessions, job queues
Typesense	8108	typesense/typesense:26.0	Full-text and faceted search

FalkorDB ≠ Redis

FalkorDB (port 6379) and Redis (port 6380) are separate instances. FalkorDB is a Redis-protocol graph database used for scripture data. Redis is a general-purpose cache/queue. Never confuse them in configuration.

Browser-Based Interfaces

Every URL you can open in a browser during local development:

Interface	URL	Purpose
Web App	http://localhost:3002	User-facing scripture reader
Admin Dashboard	http://localhost:3001	Internal admin dashboard
Docs Site	http://localhost:3003	Internal engineering docs (Docusaurus)
Grafana	http://localhost:3000	Dashboards, logs, traces, metrics
Alloy UI	http://localhost:12345	Grafana Alloy collector debug interface
Content API Docs	http://localhost:8100/docs	Swagger UI for Content service
Content API ReDoc	http://localhost:8100/redoc	ReDoc for Content service
AI API Docs	http://localhost:8400/docs	Swagger UI for AI service
AI API ReDoc	http://localhost:8400/redoc	ReDoc for AI service
FalkorDB Browser	http://localhost:3004	Graph database explorer (Cypher)
RedisInsight	http://localhost:5540	Redis GUI for keys, commands, monitor

tip

For detailed descriptions, default credentials, and optional tools for data stores that lack a web UI, see the Web Interfaces guide.

Request Flow

Browser / Mobile App
       │
       ▼
   Gateway (8080)     ← JWT validation, rate limiting, CORS
       │
       ├──► Content (8100)   ← Scripture queries → FalkorDB (6379)
       ├──► Auth (8200)      ← User management   → PostgreSQL (5432)
       ├──► Billing (8300)   ← Subscriptions      → PostgreSQL (5432)
       ├──► AI (8400)        ← LLM features       → Redis (6380) cache
       └──► Notifications (8500) ← Push/email     → Redis (6380) streams

Running Individual Services

# Frontend apps
pnpm dev:web                    # Web app → localhost:3002
pnpm dev:mobile                 # Expo mobile app

# Backend services
cd services/gateway && go run ./cmd/server                                             # → :8080
cd services/content && uv run uvicorn gospelib_content.main:create_app --factory --reload --port 8100
cd services/auth && go run ./cmd/server                                                # → :8200
cd services/billing && go run ./cmd/server                                             # → :8300
cd services/ai && uv run uvicorn gospelib_ai.main:create_app --factory --reload --port 8400
cd services/notifications && go run ./cmd/server                                       # → :8500

# Ingest pipeline (CLI, not a server)
cd services/ingest && uv run gospelib-ingest run
cd services/ingest && uv run gospelib-ingest run --dry-run

Health Checks

Every HTTP service exposes /health and /ready endpoints. Check all at once:

bash tools/scripts/health-check.sh

Or check individually:

curl http://localhost:8080/health   # Gateway
curl http://localhost:8100/health   # Content
curl http://localhost:8200/health   # Auth
curl http://localhost:8300/health   # Billing
curl http://localhost:8400/health   # AI
curl http://localhost:8500/health   # Notifications

Verify It Worked

After starting pnpm dev:stack, confirm all services are running:

1. Run bash tools/scripts/health-check.sh — all services should report healthy.
2. Open http://localhost:3002 — the web app loads.
3. Run curl http://localhost:8080/health — the gateway responds.