GospeLib — Technical Overview
Version: 1.0.0 Status: Draft Last Updated: 2026-06-15 Author: GospeLib Engineering
This page was originally a monolithic 2,600-line "Exhaustive Technical Specification." That content has been decomposed into focused, maintainable pages across the Architecture, Services, Frontend, and Operations sections. This overview preserves the core thesis and design philosophy, then points you to each detailed page.
Core Thesis
GospeLib starts as a solo-founder product and must eventually support tens of thousands of subscribers. The architecture accomplishes two competing goals simultaneously: be buildable by one person on day one, and never require a rewrite to reach enterprise scale.
The failure mode to avoid is "startup architecture" -- early decisions that bake in assumptions forcing a complete rewrite when the product achieves traction. Instead, we adopt evolutionary architecture: add complexity only where it is earned, but design every seam so that complexity can be added without breaking what exists.
Architecture Principles
- Language-right, not TypeScript-by-default. Each service uses the language whose ecosystem best matches its problem domain (Go for high-throughput gateways, Python for graph queries and AI, TypeScript for UI).
- Shared infrastructure, independent deployability. Services share config schemas, CI/CD patterns, and logging conventions -- but each builds, tests, and deploys independently. Shared logic lives in explicitly versioned packages.
- Seams before premature splitting. Logically distinct services may initially run in the same process, but are authored as separate modules with their own API contracts from the start.
- Infrastructure as code, from day one. Even local development runs through Docker Compose driven by the same variable definitions used in production.
- Observability is not optional. Every service emits structured JSON logs, OpenTelemetry metrics, and distributed traces with correlation IDs.
- Data at the boundary. Services communicate through well-typed contracts (OpenAPI). Internal data models are never exposed directly.
- The graph is the product. FalkorDB is not a cache or secondary store -- it IS the product. PostgreSQL handles operational data that does not belong in the graph.
Growth Phases
| Phase | Timeline | Scale | Key Constraints |
|---|---|---|---|
| Phase 1: Solo/Seed | Months 0-18 | 1-3 engineers, 0-10K users | Speed of execution, minimal ops overhead |
| Phase 2: Growth | Months 18-48 | 3-12 engineers, 10K-100K users | Team coordination, service independence, horizontal scale |
| Phase 3: Enterprise | Month 48+ | 12+ engineers, 100K+ users | Compliance, SLA, multi-region, data residency |
Detailed Documentation Map
Architecture
| Topic | Page | Covers |
|---|---|---|
| Monorepo structure | Monorepo | Nx workspace, pnpm/uv/Go modules, directory layout, naming conventions |
| Technology stack | Stack Decisions | Language-by-service rationale, decision matrix, alternatives rejected |
| Data architecture | Data Overview | Storage layer summary, FalkorDB, PostgreSQL, Redis, Typesense |
| Graph database | FalkorDB | Cypher queries, schema, connection pooling |
| Relational database | PostgreSQL | User/billing/study schemas, pgvector embeddings |
| Cache and queues | Redis | Key schema, rate limiting, job queues, session cache |
| Search | Typesense | Collection schemas, indexing strategy |
| Graph schemas | Schemas | Node/edge types, property definitions |
| Inter-service communication | Communication | REST contracts, response envelope, request routing |
| Security | Security Overview | Auth flow, entitlements, secrets management |
| Scaling strategy | Scaling | Phase-based scaling, horizontal scaling patterns |
| Repository map | Repo Map | Full annotated directory tree |
Services
| Service | Page | Language | Port |
|---|---|---|---|
| API Gateway | Gateway | Go (chi) | 8080 |
| Content API | Content | Python (FastAPI) | 8100 |
| Auth | Auth | Go | 8200 |
| Billing | Billing | Go | 8300 |
| AI Features | AI | Python (FastAPI) | 8400 |
| Notifications | Notifications | Go | 8500 |
| Ingest Pipeline | Ingest | Python (CLI) | -- |
Frontend
| Topic | Page | Covers |
|---|---|---|
| Frontend overview | Frontend | Architecture summary, rendering strategy |
| Design system | Design System | Tokens, components, cross-platform primitives |
| Web app | App Router | Next.js 15, RSC, ISR, client reader |
| Mobile app | Mobile | Expo, React Native, offline-first |
| State management | State | Zustand, TanStack Query |
| Shared UI | Shared UI | @gospelib/ui, @gospelib/sdk, @gospelib/types |
Operations
| Topic | Page | Covers |
|---|---|---|
| Infrastructure | Infrastructure | Terraform, Kubernetes, Docker Compose |
| CI/CD | CI/CD | GitHub Actions, ArgoCD, Nx Cloud |
| Monitoring | Monitoring | OpenTelemetry, Prometheus, Grafana, Loki, Tempo, Sentry |
| Deployment | Deployment | Staging, production, rollback procedures |
API Reference
| Topic | Page |
|---|---|
| Content API | Content Endpoints |
| AI API | AI Endpoints |
| Auth API | Auth Endpoints |
| Billing API | Billing Endpoints |
| Error codes | Error Handling |