Nginx
Gateway
Provides one browser-facing origin and routes page, API, WebSocket, and static-file requests.
Loading route
Technical architecture
How Little Daily Joys works
A concise, implementation-focused view for engineers, security reviewers, operators, and technical partners.
System map
A modular web application with isolated background work
The browser sees a single secure origin. Behind it, the gateway separates interactive web traffic from APIs while a dedicated scheduler handles time-based generation, embedding, and delivery.
Client
Browser
Family, patient, public, and administrator interfaces.
Application edge
Nginx gateway
Routes pages to Next.js and API calls to FastAPI.
Next.js frontend
Pages, forms, and client state
FastAPI backend
Domain APIs, security, and orchestration
PostgreSQL 16 + pgvector
Transactional data and vector search
Scheduler
Pre-generation, embedding jobs, timed delivery
AI providers
LLMs, embeddings, image generation, and audio via OpenRouter
External services
Email, SMS, news, weather, and media sources
Runtime components
Clear responsibilities at each layer
The backend is a modular monolith: business domains share one API deployment and database, while background scheduling remains a separate process.
Next.js + React + TypeScript
Web application
Renders public, family, patient, and administration experiences using the App Router.
FastAPI + Python
Application API
Owns authentication, authorization, business rules, provider orchestration, and JSON contracts.
APScheduler + FastAPI
Background processing
Runs scheduled newsletter generation, RAG embedding jobs, and delivery independently from interactive requests.
PostgreSQL + SQLAlchemy + Alembic
System of record
Stores accounts, families, profiles, provider settings, newsletters, RAG vectors, billing, and scheduled jobs.
pgvector + PostgreSQL full-text
Vector search
Hybrid semantic and lexical retrieval for story lore and family memories, co-located with transactional data.
Host-mounted filesystem
Runtime storage
Holds generated media, uploads, cached audio, PDFs, logs, and other recoverable runtime artifacts.
AI and content capabilities
Two products, one orchestration core
Little Daily Joys serves cognitive-care families with daily newsletters and serves writers with a storytelling workspace. Both draw on the same AI orchestration, cost tracking, and provider configuration layer.
Newsletter content engine
90+ modular providers (comics, puzzles, weather, news, nostalgia, music, and more) assemble profile-driven newsletters. Deterministic providers run without AI; AI-assisted providers use configured models with caching, validation, and variety controls.
Family memory RAG
Family-authored memories and safe profile facts are chunked, embedded, and retrieved with hybrid vector + full-text search. Retrieved context is wrapped in an untrusted-data boundary, and generated prose is validated before it reaches a newsletter or memory chat.
Story lore RAG
Uploaded world documents are indexed into pgvector chunks. Story chat answers questions using hybrid retrieval with lexical fallback, and every query is logged for audit.
Storytelling suite
Worlds, characters, acts, scenes, brainstorming, and guided story wizards share one AI orchestration layer with per-user model configuration and cost attribution.
Audio narration (TTS)
Published family stories can be narrated scene by scene. Audio is synthesized through OpenRouter, cached on the filesystem, and served with selectable narrator voices.
Delivery channels
Newsletters and stories reach readers through email, SMS, PDF export, and the in-app reader, with per-family channel configuration.
Interactive request flow
Same-origin by design
The browser never needs an internal container hostname. Cookies and API requests stay on the application origin.
- 1
Browser
Requests a page or calls the same-origin /api/v1 interface.
- 2
Nginx gateway
Routes UI traffic to Next.js and API or WebSocket traffic to FastAPI.
- 3
Application services
Authenticate the caller, apply domain rules, and orchestrate work.
- 4
Data and providers
Read or write PostgreSQL and call configured external services when required.
Newsletter pipeline
Profile-driven content, assembled before delivery
Each provider produces a focused item using approved profile preferences, provider configuration, and — where enabled — retrieved family memories.
- 01Load the patient profile, newsletter configuration, schedule, and enabled providers.
- 02Build scoped context and invoke deterministic or AI-assisted providers as configured.
- 03For RAG-enabled providers, retrieve relevant family memories with hybrid search and format them inside a prompt-safety boundary.
- 04Record generated items, retrieval provenance, and cost attribution in the database.
- 05Assemble the newsletter, render media and audio where applicable, and deliver through the configured channel.
Retrieval-augmented generation
Grounded answers with privacy and injection defenses
Two independent RAG subsystems share the same pgvector foundation but serve different products, with different indexing models and safety postures.
Family memory RAG
Asynchronous, durable, privacy-first
- • Family writes are versioned and queued; the scheduler claims embedding jobs with leases and retries with exponential backoff.
- • Zero-downtime model swaps: a new vector generation is built while the old one serves, then activated atomically.
- • Retrieved context is JSON-encoded and escaped inside an untrusted boundary; output is validated against memory-testing questions and long verbatim quoting.
- • Embedding inputs and billing logs never contain family text; retrieval logs store opaque IDs only.
- • Fallbacks everywhere: an embedding outage degrades to profile-based generation and never blocks newsletter delivery.
Story lore RAG
Synchronous, world-scoped
- • Uploaded world documents are chunked, embedded, and persisted as pgvector chunks scoped by world.
- • Story chat uses hybrid retrieval (cosine similarity + full-text ranking) with a pure lexical fallback if embeddings are unavailable.
- • Every retrieval query is logged for audit and cost attribution.
Security and data
Server-enforced trust boundaries
Navigation controls improve usability, but authorization decisions are made by the backend. Secrets and provider credentials remain in environment-specific runtime configuration and are not shipped to the browser.
Identity
Browser sessions use an HttpOnly access-token cookie. API clients may use bearer authentication, and patient access has a separate ordered-picture flow.
Authorization
FastAPI dependencies and ownership checks enforce active-user, family, patient, and administrator boundaries, including per-family RAG membership checks.
AI safety
Prompt-injection defenses, output validation, provider allowlists, and per-user cost tracking apply to every AI-assisted path.
Persistence
PostgreSQL holds transactional data and vectors. Alembic versions schema changes; runtime files and database volumes are backed up separately.
Deployment and operations
The same container model across environments
Docker Compose defines the application services. Development and production use environment-specific configuration, domains, data volumes, and credentials without changing application code.
| Concern | Development | Production |
|---|---|---|
| Entry point | Local Docker gateway | HTTPS host proxy to Docker gateway |
| Configuration | Development runtime environment | Production runtime environment with managed secrets |
| State | Dedicated development database and volumes | Dedicated persistent database and runtime volumes |
| Release safety | Unit, integration, build, and browser tests | Migrations, health checks, backups, and smoke checks |
This page describes the current high-level implementation. Internal route names may retain legacy Care Circle or Ink & Quill identifiers while the public product is Little Daily Joys.