Repository Map

This document defines the naming conventions and file organization rules for the GospeLib monorepo. For a walkthrough of the directory layout, see the Repository Tour. For monorepo tooling (Nx, pnpm, uv), see Monorepo & Tooling.

Top-Level Structure (Quick Reference)

gospelib/
├── apps/           # Frontend applications (Next.js, Expo)
├── services/       # Backend microservices (Go, Python)
├── packages/       # Shared TypeScript/Python libraries
├── infra/          # Docker Compose, Terraform, Kubernetes, Grafana
├── tools/          # Developer scripts and Nx generators
├── data/           # Book registry, corpus-v2, test fixtures
├── docs/           # Specifications, ADRs, guides
└── (root configs)  # nx.json, package.json, tsconfig.base.json, etc.

For details on each directory, see the Repository Tour.

---

Naming Conventions

File Naming

Context	Convention	Example
TypeScript / JavaScript files	kebab-case.ts	passage-reader.tsx, use-auth.ts
React components	PascalCase.tsx	PassageReader.tsx, SearchBar.tsx
React component directories	PascalCase/	PassageReader/PassageReader.tsx
Go files	snake_case.go	passage_handler.go, rate_limiter.go
Python files	snake_case.py	scripture_text.py, batch_writer.py
Shell scripts	kebab-case.sh	reset-db.sh, gen-types.sh
Terraform files	snake_case.tf	main.tf, variables.tf
YAML / JSON config	kebab-case.yaml	docker-compose.yml, plans.yaml
Markdown docs	UPPER-KEBAB-CASE.md (specs) or kebab-case.md (guides)	TECH-SPEC.md, getting-started.md
Test files (TS)	*.test.ts or *.spec.ts	passage-reader.test.tsx
Test files (Go)	*_test.go	passage_handler_test.go
Test files (Python)	test_*.py	test_scripture_text.py

Directory Naming

Context	Convention	Example
Top-level concerns	kebab-case or singular noun	apps/, services/, packages/
App/service sub-dirs	kebab-case	components/, hooks/, routes/
Component directories	PascalCase (React)	Button/, PassageReader/
Python packages	snake_case	scripture_text/, db/
Go packages	lowercase (single word preferred)	handler/, middleware/, config/

Package and Service Naming

Entity	Convention	Example
npm packages	@gospelib/<name>	@gospelib/ui, @gospelib/sdk
Docker images / K8s services	gospelib-<name>	gospelib-content, gospelib-gateway
Python packages	gospelib_<name>	gospelib_ingest
Go modules	github.com/gospelib/main/services/<name>	github.com/gospelib/main/services/gateway

Environment Variable Naming

Pattern: GOSPELIB_<SERVICE>_<KEY>

Category	Example
Service-specific	GOSPELIB_CONTENT_DB_URL, GOSPELIB_BILLING_STRIPE_KEY
Shared infra	GOSPELIB_PG_URL, GOSPELIB_REDIS_URL, GOSPELIB_FALKORDB_URL
Feature flags	GOSPELIB_FF_<FLAG_NAME>

Third-party variables use their standard names: CLERK_SECRET_KEY, STRIPE_SECRET_KEY, ANTHROPIC_API_KEY.

Database and Redis Naming

Store	Convention	Example
PostgreSQL schemas	gl_<name>	gl_users, gl_subscriptions
FalkorDB graph name	gospelib	--
Redis key namespaces	gl:<service>:<key>	gl:content:passage:gen.1.1
Redis Streams	gl:events:<domain>	gl:events:notifications

Data ID Conventions

Entity	Pattern	Example
Passage IDs	{bookId}.{chapter}.{verse}	gen.1.1
JST Passage IDs	jst-{bookId}.{chapter}.{verse}	jst-gen.1.1
Translation IDs	{bookId}.{chapter}.{verse}:{translation}	gen.1.1:esv
Word IDs (Strong's)	{H|G}{NNNN} (zero-padded 4-digit)	H0430, G0056
TG Entry IDs	tg:{slugified-title}	tg:angels
BD Entry IDs	bd:{slugified-title}	bd:aaron
Person IDs	person:{slug}.{N}	person:aaron.1
Place IDs	place:{slug}	place:ammonihah
Index Topic IDs	topic:{slug}	topic:aaronic-priesthood
Section IDs	{commentaryId}.t{XX}.s{XX}	byu-ntc-revelation.t02.s01

---

File Organization Rules

When to Split a File

Signal	Action
File exceeds 300 lines (TS/Python) or 500 lines (Go)	Extract related functions into a new module
File handles more than one domain concern	Split by concern (e.g., separate auth from billing logic)
File has more than 5 exports that are unrelated	Group related exports into sub-modules
A component has more than 3 sub-components inline	Extract sub-components to their own files

When to Create a New Directory

Signal	Action
3+ related files that share a theme	Group into a named directory
A feature needs its own routes + components + hooks	Create a feature directory
A test fixture set is shared across multiple test files	Move to fixtures/ directory

When to Create a New Package vs. Module

Choose Package When	Choose Module When
Code is consumed by 2+ apps or services	Code is used by only one app or service
Code has its own versioning needs	Code changes in lockstep with its consumer
Code could be open-sourced independently	Code is tightly coupled to business logic

Co-location Principles

Rule	Rationale
Tests next to source (Go, TS components)	Reduces navigation; makes coverage gaps visible
Types next to implementation	Keeps contracts close to where they're enforced
Styles next to components (CSS Modules / Tailwind)	Component is self-contained
Python tests in tests/	Python convention; pytest discovery expects it
Fixtures near tests	tests/fixtures/ or data/fixtures/ -- never scattered

Index / Barrel File Policy

Language	Policy
TypeScript	One index.ts per package as the public API surface. Internal directories may have index.ts only if they represent a clear module boundary. Do not create deeply nested barrel files.
Python	__init__.py in every package (required). Keep imports minimal -- prefer explicit imports over from module import *.
Go	No barrel files. Use package-level exports directly.

Create on First Use

Do not create empty placeholder directories. Every directory is created when its first file is added. The structure is fully defined in this document and the Repository Tour, so contributors know where things go without empty directories as hints.

---

Related Pages

Topic	Page
Directory walkthrough	Repository Tour
Monorepo tooling (Nx, pnpm)	Monorepo & Tooling
Service details	Services Overview
Testing conventions	Testing
Port assignments	Port Map
Architecture decisions	Decisions
Data schemas	Schemas
Tech stack	Stack