Deployment Overview
GospeLib runs as a set of containerized microservices on Kubernetes, backed by managed data stores on AWS. This guide covers the deployment architecture, environment topology, and prerequisites.
Service Inventory
| Service | Language | Port | Runtime | Purpose |
|---|---|---|---|---|
| Gateway | Go (chi) | 8080 | Container | API routing, JWT validation, rate limiting |
| Content | Python (FastAPI) | 8100 | Container | Scripture graph queries (FalkorDB + Typesense) |
| Auth | Go (chi) | 8200 | Container | Authentication wrapper (Clerk) |
| Billing | Go (chi) | 8300 | Container | Subscriptions (Stripe) |
| AI | Python (FastAPI) | 8400 | Container | LLM orchestration (Anthropic, OpenAI) |
| Notifications | Go (chi) | 8500 | Container | Push + email (FCM, APNs, Resend) |
| Ingest | Python (Click) | — | K8s Job | Corpus → FalgorDB pipeline |
| Web | Next.js | 3000 | AWS Amplify | Web reader + marketing |
| Admin | Next.js | 3001 | AWS Amplify | Internal dashboard |
| Mobile | React Native (Expo) | — | EAS Build | iOS + Android apps |
Data Stores
| Store | Engine | Staging | Production |
|---|---|---|---|
| FalkorDB | Redis-based graph DB | K8s pod | K8s pod (dedicated node) |
| PostgreSQL | pg16 + pgvector | RDS db.t3.micro | RDS db.r6g.large |
| Redis | Redis 7 | ElastiCache t3.micro | ElastiCache r6g.large |
| Typesense | Typesense 26 | K8s pod | K8s pod (dedicated node) |
warning
FalkorDB (port 6379) and general Redis (port 6380) are separate instances. Do not confuse them.
Environment Topology
┌──────────────────────────┬─────────────────────────────┐
│ STAGING │ PRODUCTION │
│ staging.gospelib.com │ gospelib.com │
│ │ api.gospelib.com │
│ EC2 t3.micro (k3s) │ EKS Cluster │
│ ├ all services (×1) │ ├ all services (×2) │
│ ├ falkordb │ ├ falkordb │
│ └ typesense │ └ typesense │
│ │ │
│ RDS db.t3.micro │ RDS db.r6g.large │
│ ElastiCache t3.micro │ ElastiCache r6g.large │
│ ~$2.50/month │ ~$213/month │
└──────────────────────────┴─────────────────────────────┘
Design Principle: Staging = Production
Staging mirrors production in every meaningful way:
- Same Docker images — identical container builds from the same ECR registry
- Same Kubernetes manifests — Kustomize overlays only change namespace, replica count, and resource limits
- Same database engines — RDS PostgreSQL, ElastiCache Redis, FalkorDB, Typesense (just smaller instances)
- Same networking — Ingress, TLS, DNS structure, CloudFront CDN
- Same secrets management — AWS Secrets Manager with per-environment paths
- Same CI/CD pipeline — GitHub Actions → ECR → ArgoCD
- Same monitoring stack — Grafana, Prometheus, Loki
The only differences are instance sizes and replica counts.
Prerequisites
Required Accounts
| Account | Purpose | Free Tier? |
|---|---|---|
| AWS | All infrastructure | Yes (12 months) |
| GitHub | Source code, CI/CD | Yes |
| Clerk | Authentication | Yes (10K MAU) |
| Stripe | Billing | Yes (test mode) |
| Expo / EAS | Mobile builds | Yes (limited) |
| Anthropic | Claude API | Pay-as-you-go |
| OpenAI | GPT API | Pay-as-you-go |
| Resend | Transactional email | Yes (100/day) |
| Sentry | Error tracking | Yes (developer) |
Required CLI Tools
node >= 22.0 # JS runtime
pnpm >= 9.15 # Package manager
go >= 1.23 # Go services
python3 >= 3.12 # Python services
uv latest # Python package manager
docker latest # Container builds
terraform >= 1.9 # Infrastructure as Code
aws latest # AWS CLI v2
kubectl latest # Kubernetes control
kustomize latest # K8s manifest management
k3sup latest # k3s installer (staging)
argocd latest # ArgoCD CLI
helm latest # Helm charts
Repository Secrets (GitHub Actions)
| Secret | Description |
|---|---|
AWS_ROLE_ARN | IAM OIDC role ARN |
ECR_URL | ECR registry URL |
CLERK_SECRET_KEY | Clerk API key (per env) |
STRIPE_SECRET_KEY | Stripe API key (per env) |
ANTHROPIC_API_KEY | Anthropic API key |
OPENAI_API_KEY | OpenAI API key |
RESEND_API_KEY | Resend API key |
SENTRY_DSN | Sentry DSN |
EXPO_TOKEN | Expo/EAS access token |
NX_CLOUD_ACCESS_TOKEN | Nx Cloud cache token |
Infrastructure as Code
All infrastructure is defined in infra/terraform/:
infra/terraform/
├── modules/
│ ├── eks/ # EKS cluster
│ ├── rds/ # PostgreSQL
│ ├── elasticache/ # Redis
│ ├── s3/ # S3 buckets
│ ├── ecr/ # Container registries
│ ├── cloudfront/ # CDN
│ ├── route53/ # DNS
│ └── secrets/ # AWS Secrets Manager
├── environments/
│ ├── staging/
│ └── production/
├── main.tf
├── variables.tf
└── outputs.tf
Kubernetes manifests use Kustomize with base + overlay pattern:
infra/k8s/
├── base/ # Base manifests for all services
├── overlays/
│ ├── staging/ # Staging overrides (1 replica, small resources)
│ └── production/ # Production overrides (2 replicas, larger resources)
└── jobs/
├── ingest-full.yaml
└── ingest-incremental.yaml
Next Steps
- Deploy to Staging — Set up the staging environment on k3s
- Deploy to Production — Promote to EKS with approval gates
- Monitoring & Alerting — Set up the observability stack