# ncastaldi/opinionated-recipes architecture

> Architecture diagram of the GitHub repository ncastaldi/opinionated-recipes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ncastaldi/opinionated-recipes
- Repository: https://github.com/ncastaldi/opinionated-recipes

## Overview

Opinionated Recipes is an early-stage, self-hosted Cooklang recipe manager. The current product is a walking skeleton: the web shell, Fastify API with liveness routing, and BullMQ worker run, but recipe features are not implemented. The documented target workflow accepts typed, imported, or migrated recipes, normalizes them to house style, and stores canonical Cooklang in Postgres; optional embeddings and chat are also planned. The graph distinguishes implemented components from documented capabilities. Recipe-stage links rely on the README, not inspected implementations.

Main entry points: [`apps/api/src/server.ts`](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/server.ts) (API server), [`apps/worker/src`](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src) (House-style normalization), [`apps/worker/src/worker.ts`](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/worker.ts) (Job worker), [`apps/worker/src/jobs.ts`](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/jobs.ts) (Job dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Recipe SPA<br/>[app.tsx]"]
  node_nginx["Web nginx"]
end

subgraph group_api["API service"]
  node_api_server["API server<br/>[server.ts]"]
  node_api_app["Fastify app<br/>[app.ts]"]
  node_health["Liveness route<br/>[health.ts]"]
  node_config["Environment config<br/>[index.ts]"]
end

subgraph group_recipe["Recipe processing"]
  node_recipe_input["Recipe inputs"]
  node_normalization["House-style normalization"]
  node_cooklang["Cooklang parser<br/>[parse.ts]"]
  node_job_worker["Job worker<br/>[worker.ts]"]
  node_job_router["Job dispatch<br/>[jobs.ts]"]
end

subgraph group_state["State and AI"]
  node_db_client["Database client<br/>[index.ts]"]
  node_postgres[("Postgres")]
  node_redis["Redis queue"]
  node_embeddings["Local embeddings"]
  node_ollama["Ollama"]
  node_chat["Recipe chat"]
  node_claude["Claude API"]
end

node_household(("Household user"))

node_household -.->|"uses"| node_web
node_web -.->|"served by"| node_nginx
node_nginx -.->|"proxies requests"| node_api_server
node_api_server -->|"loads config"| node_config
node_api_server -->|"builds app"| node_api_app
node_api_app -->|"registers route"| node_health
node_api_server -.->|"enqueues jobs"| node_redis
node_redis -.->|"delivers jobs"| node_job_worker
node_job_worker -->|"loads config"| node_config
node_job_worker -->|"dispatches job"| node_job_router
node_recipe_input -.->|"normalizes"| node_normalization
node_normalization -.->|"parses Cooklang"| node_cooklang
node_normalization -.->|"saves canonical recipe"| node_db_client
node_db_client -.->|"reads and writes"| node_postgres
node_job_router -.->|"dispatches processing"| node_normalization
node_job_router -.->|"dispatches embedding"| node_embeddings
node_embeddings -.->|"requests embeddings"| node_ollama
node_chat -.->|"requests chat"| node_claude

click node_web "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/web/src/app.tsx"
click node_nginx "https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/web"
click node_api_server "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/server.ts"
click node_api_app "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/app.ts"
click node_health "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/routes/health.ts"
click node_config "https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/config/src/index.ts"
click node_recipe_input "https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src"
click node_normalization "https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src"
click node_cooklang "https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/engine/src/parse.ts"
click node_job_worker "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/worker.ts"
click node_job_router "https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/jobs.ts"
click node_db_client "https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/db/src/index.ts"
click node_embeddings "https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src"
click node_chat "https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/api/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_nginx,node_household toneBlue
class node_api_server,node_api_app,node_health,node_config toneAmber
class node_recipe_input,node_normalization,node_cooklang,node_job_worker,node_job_router toneMint
class node_db_client,node_postgres,node_redis,node_embeddings,node_ollama,node_chat,node_claude toneRose
```

## Components

### Web experience

- [Recipe SPA](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/web/src/app.tsx): `apps/web/src/app.tsx`
- [Web nginx](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/web): `apps/web`

### API service

- [API server](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Fastify app](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Liveness route](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/api/src/routes/health.ts): `apps/api/src/routes/health.ts`
- [Environment config](https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/config/src/index.ts): `packages/config/src/index.ts`

### Recipe processing

- [Recipe inputs](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src): `apps/worker/src`
- [House-style normalization](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src): `apps/worker/src`
- [Cooklang parser](https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/engine/src/parse.ts): `packages/engine/src/parse.ts`
- [Job worker](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/worker.ts): `apps/worker/src/worker.ts`
- [Job dispatch](https://github.com/ncastaldi/opinionated-recipes/blob/main/apps/worker/src/jobs.ts): `apps/worker/src/jobs.ts`

### State and AI

- [Database client](https://github.com/ncastaldi/opinionated-recipes/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`
- **Postgres**
- **Redis queue**
- [Local embeddings](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/worker/src): `apps/worker/src`
- **Ollama**
- [Recipe chat](https://github.com/ncastaldi/opinionated-recipes/tree/main/apps/api/src): `apps/api/src`
- **Claude API**

### Other components

- **Household user**

## Connections

- Household user → Recipe SPA: uses (evidence: `README.md`)
- Recipe SPA → Web nginx: served by (evidence: `README.md`)
- Web nginx → API server: proxies requests (evidence: `README.md`)
- API server → Environment config: loads config (evidence: `apps/api/src/server.ts`)
- API server → Fastify app: builds app (evidence: `apps/api/src/server.ts`)
- Fastify app → Liveness route: registers route (evidence: `apps/api/src/app.ts`)
- API server → Redis queue: enqueues jobs (evidence: `README.md`)
- Redis queue → Job worker: delivers jobs (evidence: `README.md`)
- Job worker → Environment config: loads config (evidence: `apps/worker/src/worker.ts`)
- Job worker → Job dispatch: dispatches job (evidence: `apps/worker/src/worker.ts`)
- Recipe inputs → House-style normalization: normalizes (evidence: `README.md`)
- House-style normalization → Cooklang parser: parses Cooklang (evidence: `README.md`)
- House-style normalization → Database client: saves canonical recipe (evidence: `README.md`)
- Database client → Postgres: reads and writes (evidence: `README.md`)
- Job dispatch → House-style normalization: dispatches processing (evidence: `README.md`)
- Job dispatch → Local embeddings: dispatches embedding (evidence: `README.md`)
- Local embeddings → Ollama: requests embeddings (evidence: `README.md`)
- Recipe chat → Claude API: requests chat (evidence: `README.md`)
