# julianpoy/recipesage architecture

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

- Interactive diagram: https://gitdiagram.com/julianpoy/recipesage
- Repository: https://github.com/julianpoy/recipesage

## Overview

RecipeSage is a collaborative recipe organizer spanning web/mobile clients, API services, and asynchronous jobs. A typical import starts with a user submitting a recipe source, proceeds through API upload and queued parsing, and ends with recipes available for collection and search. The product also supports meal planning, shopping lists, social collaboration, discovery, nutrition, and AI cooking assistance. The README establishes these capabilities; source-level links below are limited to relationships visible in excerpts or the source index, so unsampled feature wiring is not asserted.

Main entry points: [`packages/trpc/src/trpc.ts`](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/trpc.ts) (TRPC procedures), [`packages/frontend/src/app/app.routes.ts`](https://github.com/julianpoy/recipesage/blob/master/packages/frontend/src/app/app.routes.ts) (RecipeSage UI), [`packages/backend/src/app.ts`](https://github.com/julianpoy/recipesage/blob/master/packages/backend/src/app.ts) (HTTP server), [`packages/express/src/routes/import/job/cookbookmanagercom.ts`](https://github.com/julianpoy/recipesage/blob/master/packages/express/src/routes/import/job/cookbookmanagercom.ts) (Import upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client applications"]
  node_frontend["RecipeSage UI<br/>[app.routes.ts]"]
end

subgraph group_api["API and domain"]
  node_backend["HTTP server<br/>[app.ts]"]
  node_express["REST handlers<br/>[defineHandler.ts]"]
  node_import_endpoint["Import upload"]
  node_trpc["TRPC procedures<br/>[trpc.ts]"]
  node_recipes["Recipe operations<br/>[recipesRouter.ts]"]
  node_users["Account operations<br/>[usersRouter.ts]"]
  node_shopping["Shopping lists"]
  node_meal_plans["Meal planning<br/>[mealPlansRouter.ts]"]
  node_discover["Recipe discovery<br/>[discoverRouter.ts]"]
  node_ml["AI and extraction<br/>[mlRouter.ts]"]
  node_social["Sharing and profiles<br/>[messagesRouter.ts]"]
end

subgraph group_jobs["Background processing"]
  node_worker["Queue worker<br/>[worker.ts]"]
  node_job_dispatch["Job dispatcher"]
  node_import_dispatch["Import dispatcher"]
  node_cookbook_parser["Cookbook parser"]
  node_job_queue["Job queue<br/>[JobQueueItem.ts]"]
end

subgraph group_data["Local and shared data"]
  node_localstore[("Offline storage")]
end

node_user(("Recipe user"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"requests API"| node_backend
node_backend -->|"mounts routes"| node_express
node_backend -->|"mounts middleware"| node_trpc
node_express -.->|"defines handlers"| node_import_endpoint
node_user -->|"uploads source"| node_import_endpoint
node_import_endpoint -->|"enqueues job"| node_job_queue
node_worker -->|"processes jobs"| node_job_dispatch
node_job_dispatch -->|"dispatches imports"| node_import_dispatch
node_import_dispatch -->|"dispatches format"| node_cookbook_parser
node_trpc -.->|"registers procedures"| node_recipes
node_trpc -.->|"registers procedures"| node_users
node_trpc -.->|"registers procedures"| node_shopping
node_user -->|"plans meals"| node_meal_plans
node_user -->|"organizes shopping"| node_shopping
node_user -->|"discovers recipes"| node_discover
node_user -->|"uses cooking assistant"| node_ml
node_user -->|"shares and collaborates"| node_social
node_frontend -->|"restores session"| node_localstore
node_localstore -->|"queries user"| node_trpc
node_user -->|"works offline"| node_frontend

click node_frontend "https://github.com/julianpoy/recipesage/blob/master/packages/frontend/src/app/app.routes.ts"
click node_localstore "https://github.com/julianpoy/recipesage/blob/master/packages/frontend/src/app/utils/appIdbStorageManager.ts"
click node_backend "https://github.com/julianpoy/recipesage/blob/master/packages/backend/src/app.ts"
click node_express "https://github.com/julianpoy/recipesage/blob/master/packages/express/src/defineHandler.ts"
click node_import_endpoint "https://github.com/julianpoy/recipesage/blob/master/packages/express/src/routes/import/job/cookbookmanagercom.ts"
click node_trpc "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/trpc.ts"
click node_recipes "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/recipes/recipesRouter.ts"
click node_users "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/users/usersRouter.ts"
click node_shopping "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/shoppingLists/shoppingListsRouter.ts"
click node_worker "https://github.com/julianpoy/recipesage/blob/master/packages/queue-worker/src/worker.ts"
click node_job_dispatch "https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/processWorkerJob.ts"
click node_import_dispatch "https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/import/processImportJob.ts"
click node_cookbook_parser "https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/import/handlers/cookbookManagerComImportJobHandler.ts"
click node_job_queue "https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/JobQueueItem.ts"
click node_meal_plans "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/mealPlans/mealPlansRouter.ts"
click node_discover "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/discover/discoverRouter.ts"
click node_ml "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/ml/mlRouter.ts"
click node_social "https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/messages/messagesRouter.ts"

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_frontend,node_user toneBlue
class node_backend,node_express,node_import_endpoint,node_trpc,node_recipes,node_users,node_shopping,node_meal_plans,node_discover,node_ml,node_social toneAmber
class node_worker,node_job_dispatch,node_import_dispatch,node_cookbook_parser,node_job_queue toneMint
class node_localstore toneRose
```

## Components

### Client applications

- [RecipeSage UI](https://github.com/julianpoy/recipesage/blob/master/packages/frontend/src/app/app.routes.ts): `packages/frontend/src/app/app.routes.ts`

### API and domain

- [HTTP server](https://github.com/julianpoy/recipesage/blob/master/packages/backend/src/app.ts): `packages/backend/src/app.ts`
- [REST handlers](https://github.com/julianpoy/recipesage/blob/master/packages/express/src/defineHandler.ts): `packages/express/src/defineHandler.ts`
- [Import upload](https://github.com/julianpoy/recipesage/blob/master/packages/express/src/routes/import/job/cookbookmanagercom.ts): `packages/express/src/routes/import/job/cookbookmanagercom.ts`
- [TRPC procedures](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/trpc.ts): `packages/trpc/src/trpc.ts`
- [Recipe operations](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/recipes/recipesRouter.ts): `packages/trpc/src/procedures/recipes/recipesRouter.ts`
- [Account operations](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/users/usersRouter.ts): `packages/trpc/src/procedures/users/usersRouter.ts`
- [Shopping lists](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/shoppingLists/shoppingListsRouter.ts): `packages/trpc/src/procedures/shoppingLists/shoppingListsRouter.ts`
- [Meal planning](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/mealPlans/mealPlansRouter.ts): `packages/trpc/src/procedures/mealPlans/mealPlansRouter.ts`
- [Recipe discovery](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/discover/discoverRouter.ts): `packages/trpc/src/procedures/discover/discoverRouter.ts`
- [AI and extraction](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/ml/mlRouter.ts): `packages/trpc/src/procedures/ml/mlRouter.ts`
- [Sharing and profiles](https://github.com/julianpoy/recipesage/blob/master/packages/trpc/src/procedures/messages/messagesRouter.ts): `packages/trpc/src/procedures/messages/messagesRouter.ts`

### Background processing

- [Queue worker](https://github.com/julianpoy/recipesage/blob/master/packages/queue-worker/src/worker.ts): `packages/queue-worker/src/worker.ts`
- [Job dispatcher](https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/processWorkerJob.ts): `packages/util/server/src/general/queue/processWorkerJob.ts`
- [Import dispatcher](https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/import/processImportJob.ts): `packages/util/server/src/general/queue/import/processImportJob.ts`
- [Cookbook parser](https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/import/handlers/cookbookManagerComImportJobHandler.ts): `packages/util/server/src/general/queue/import/handlers/cookbookManagerComImportJobHandler.ts`
- [Job queue](https://github.com/julianpoy/recipesage/blob/master/packages/util/server/src/general/queue/JobQueueItem.ts): `packages/util/server/src/general/queue/JobQueueItem.ts`

### Local and shared data

- [Offline storage](https://github.com/julianpoy/recipesage/blob/master/packages/frontend/src/app/utils/appIdbStorageManager.ts): `packages/frontend/src/app/utils/appIdbStorageManager.ts`

### Other components

- **Recipe user**

## Connections

- Recipe user → RecipeSage UI: uses (evidence: `README.md`)
- RecipeSage UI → HTTP server: requests API
- HTTP server → REST handlers: mounts routes (evidence: `packages/backend/src/app.ts`)
- HTTP server → TRPC procedures: mounts middleware (evidence: `packages/backend/src/app.ts`)
- REST handlers → Import upload: defines handlers (evidence: `packages/express/src/routes/import/job/cookbookmanagercom.ts`)
- Recipe user → Import upload: uploads source (evidence: `README.md`)
- Import upload → Job queue: enqueues job (evidence: `packages/express/src/routes/import/job/cookbookmanagercom.ts`)
- Queue worker → Job dispatcher: processes jobs (evidence: `packages/queue-worker/src/worker.ts`)
- Job dispatcher → Import dispatcher: dispatches imports (evidence: `packages/util/server/src/general/queue/processWorkerJob.ts`)
- Import dispatcher → Cookbook parser: dispatches format (evidence: `packages/util/server/src/general/queue/import/processImportJob.ts`)
- TRPC procedures → Recipe operations: registers procedures (evidence: `packages/trpc/src/procedures/recipes/recipesRouter.ts`)
- TRPC procedures → Account operations: registers procedures (evidence: `packages/trpc/src/procedures/users/usersRouter.ts`)
- TRPC procedures → Shopping lists: registers procedures (evidence: `packages/trpc/src/procedures/shoppingLists/shoppingListsRouter.ts`)
- Recipe user → Meal planning: plans meals (evidence: `README.md`)
- Recipe user → Shopping lists: organizes shopping (evidence: `README.md`)
- Recipe user → Recipe discovery: discovers recipes (evidence: `README.md`)
- Recipe user → AI and extraction: uses cooking assistant (evidence: `README.md`)
- Recipe user → Sharing and profiles: shares and collaborates (evidence: `README.md`)
- RecipeSage UI → Offline storage: restores session (evidence: `packages/frontend/src/app/utils/appIdbStorageManager.ts`)
- Offline storage → TRPC procedures: queries user (evidence: `packages/frontend/src/app/utils/appIdbStorageManager.ts`)
- Recipe user → RecipeSage UI: works offline (evidence: `README.md`)
