Content Service

The Content service is the primary consumer of FalkorDB. It translates REST requests into Cypher graph queries, caches results in Redis, and returns Pydantic-validated responses. All scripture data — passages, lexicon entries, topics, cross-references, and manuscript witnesses — flows through this service.

Quick Reference

Property	Value
Port	8100
Language	Python 3.12
Framework	FastAPI + Uvicorn
Package	gospelib_content
Entry point	src/gospelib_content/main.py → create_app()
Primary data store	FalkorDB (port 6379)
Cache	Redis (port 6380)

Responsibilities

• Passage retrieval — Single verses, chapter ranges, cross-references
• Lexicon queries — Strong's Hebrew/Greek word definitions and morphology
• Topic guide — Topical Guide and Bible Dictionary lookups
• Graph connections — Relationship traversal between passages, topics, and scholarly resources
• Search — Proxy to Typesense for full-text and faceted search
• Manuscript witnesses — Original Manuscript, Printer's Manuscript, 1830 edition comparison

Running Locally

cd services/content
uv sync
uv run uvicorn gospelib_content.main:create_app --factory --reload --port 8100

The service expects FalkorDB to be running on port 6379 and Redis on port 6380. Start infrastructure with:

pnpm infra:up

Environment Variables

Variable	Default	Description
GOSPELIB_CONTENT_PORT	8100	HTTP listen port
GOSPELIB_CONTENT_FALKORDB_URL	redis://localhost:6379	FalkorDB connection URL
GOSPELIB_CONTENT_REDIS_URL	redis://localhost:6380	Redis cache URL
GOSPELIB_CONTENT_GRAPH_NAME	gospelib	FalkorDB graph name
GOSPELIB_CONTENT_CACHE_TTL	300	Default cache TTL in seconds
GOSPELIB_CONTENT_DEBUG	false	Enable debug mode (OpenAPI docs at /docs)

Application Factory

The create_app() factory follows the standard FastAPI pattern:

# services/content/src/gospelib_content/main.py (simplified)
def create_app() -> FastAPI:
    app = FastAPI(
        title="GospeLib Content API",
        version="1.0.0",
        docs_url="/docs" if settings.debug else None,
    )

    app.include_router(health_router,        tags=["health"])
    app.include_router(cfm_router,           prefix="/api/v1", tags=["cfm"])
    app.include_router(share_router,         prefix="/api/v1", tags=["share"])
    app.include_router(commentary_router,    prefix="/api/v1", tags=["commentary"])
    app.include_router(connections_router,    prefix="/api/v1", tags=["connections"])
    app.include_router(dictionary_router,    prefix="/api/v1", tags=["dictionary"])
    app.include_router(entities_router,      prefix="/api/v1", tags=["entities"])
    app.include_router(lexicon_router,       prefix="/api/v1", tags=["lexicon"])
    app.include_router(nav_events_router,    prefix="/api/v1", tags=["nav-events"])
    app.include_router(translations_router,  prefix="/api/v1", tags=["translations"])
    app.include_router(passages_router,      prefix="/api/v1", tags=["passages"])
    app.include_router(search_router,        prefix="/api/v1", tags=["search"])
    app.include_router(topics_router,        prefix="/api/v1", tags=["topics"])

    return app

Configuration

Settings use pydantic-settings with GOSPELIB_CONTENT_ prefix:

# services/content/src/gospelib_content/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    port: int = 8100
    falkordb_url: str = "redis://localhost:6379"
    redis_url: str = "redis://localhost:6380"
    graph_name: str = "gospelib"
    cache_ttl: int = 300
    debug: bool = False

    class Config:
        env_prefix = "GOSPELIB_CONTENT_"

Health Check

curl http://localhost:8100/health
# {"status": "ok"}

Docker

FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml ./
RUN uv sync --no-dev
COPY src/ ./src/

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app /app
EXPOSE 8100
CMD ["uvicorn", "gospelib_content.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8100"]

Related Pages

• Graph Client & Caching — how queries are executed and cached
• Endpoints — all available API endpoints
• Architecture > Data > FalkorDB — graph model details