Repository Tour
The GospeLib monorepo has four main areas: apps, services, packages, and infrastructure. This page gives you the lay of the land — enough to know where to look when you need something.
Top-Level Overview
gospelib/
├── apps/ # 3 frontend applications
├── services/ # 8 backend microservices
├── packages/ # 9 shared TypeScript/Python libraries
├── infra/ # Docker Compose, Terraform, Kubernetes, Grafana
├── tools/ # Developer scripts and Nx generators
├── data/ # Book registry, corpus-v2, test fixtures
├── corpus/ # Source scripture JSON files (v1)
├── docs/ # Specifications, ADRs, guides
└── (root configs) # nx.json, package.json, tsconfig.base.json, etc.
Apps (apps/)
Three frontend applications, all TypeScript:
| App | Framework | Port | Purpose |
|---|---|---|---|
apps/web | Next.js 15 (App Router) | 3002 | User-facing scripture reader and study tools |
apps/admin | Next.js 15 (App Router) | 3001 | Internal admin dashboard |
apps/mobile | Expo 52 / React Native | — | iOS and Android mobile app |
All apps import from the shared packages/ libraries. No app imports from another app or directly from services/.
Services (services/)
Eight backend microservices, each independently deployable. Three languages:
| Service | Language | Framework | Port | What It Does |
|---|---|---|---|---|
gateway | Go | Chi v5 | 8080 | API gateway — JWT validation, rate limiting, reverse proxy |
content | Python | FastAPI | 8100 | Scripture graph queries against FalkorDB |
auth | Go | Chi v5 | 8200 | Clerk wrapper, user sync, JWT middleware |
billing | Go | Chi v5 | 8300 | Stripe subscriptions and entitlements |
ai | Python | FastAPI | 8400 | LLM-powered passage explanation, study questions |
notifications | Go | Chi v5 | 8500 | Push (APNs/FCM), email (Resend), Redis Streams |
plugin-registry | Python | FastAPI | 8500 | Plugin manifest registry, discovery, versioning |
ingest | Python | Click CLI | — | Data pipeline: JSON corpus → FalkorDB |
No service imports code from another service at runtime. Shared logic lives in packages/ (TypeScript) or is duplicated at the service boundary.
Packages (packages/)
Nine shared libraries used by apps and services:
| Package | npm Name | Purpose |
|---|---|---|
packages/core | @gospelib/core | Shared domain logic (book registry, entitlements, events, nav) |
packages/types | @gospelib/types | Shared TypeScript types (auto-generated from OpenAPI + manual) |
packages/ui | @gospelib/ui | Cross-platform React Native component library |
packages/sdk | @gospelib/sdk | Client SDK for API calls (uses openapi-fetch) |
packages/config | @gospelib/config | ESLint/TSConfig presets + Zod env schemas |
packages/schemas | gospelib-schemas | Shared Pydantic schema models (all Python services) |
packages/scripture-ref | @gospelib/scripture-ref | Scripture reference parser and formatter |
packages/plugin-sdk | @gospelib/plugin-sdk | Plugin authoring SDK for the plugin ecosystem |
packages/testing | @gospelib/testing | Shared test fixtures, mocks, helpers |
Infrastructure (infra/)
Everything needed to run and deploy the platform:
| Directory | What's Inside |
|---|---|
infra/docker/ | Docker Compose files for local data stores |
infra/terraform/ | AWS infrastructure as Terraform modules |
infra/k8s/ | Kubernetes manifests (Kustomize overlays) |
infra/grafana/ | Grafana dashboards and provisioning configs |
Other Directories
| Directory | Purpose |
|---|---|
tools/scripts/ | Shell scripts — setup.sh, health-check.sh, etc. |
tools/generators/ | Nx generators for scaffolding new services/packages |
data/ | Book registry (book_registry.json), corpus-v2 JSON files, test fixtures |
corpus/ | Legacy v1 scripture corpus (input data for the ingest pipeline) |
docs/ | ADRs, API specs, tech spec, design system spec, deployment guide |
Root Configuration Files
Key config files at the repository root:
| File | Purpose |
|---|---|
nx.json | Nx workspace configuration (task caching, affected base) |
package.json | Root dependencies, scripts, pnpm engine enforcement |
pnpm-workspace.yaml | Workspace package globs |
tsconfig.base.json | Shared TypeScript config (strict, ES2022, bundler resolution) |
eslint.config.mjs | Shared ESLint flat config |
vitest.workspace.ts | Vitest workspace runner |
commitlint.config.mjs | Conventional Commits enforcement |
For exhaustive rules on file placement, splitting heuristics, and naming conventions, see the full Repository Map.
Next Step
Ready to contribute? Head to Your First PR to learn the branching and commit workflow.