# riyazlive04/kuttystorynew architecture

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

- Interactive diagram: https://gitdiagram.com/riyazlive04/kuttystorynew
- Repository: https://github.com/riyazlive04/kuttystorynew

## Overview

KuttyStory sells personalized AI storybooks: a caregiver selects a story, uploads a child’s photo, reviews a free preview, then buys a PDF or printed book. The web storefront calls a FastAPI API; jobs are rendered asynchronously and stored for polling and fulfillment. The map includes catalog, payment, admin, and print-production capabilities alongside that main flow. Relationships are grounded in the README and SOURCE INDEX references; several internal calls and unsampled subsystems are not directly shown, so those links are omitted.

Main entry points: [`apps/api/app/tasks.py`](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/tasks.py) (Render Tasks), [`apps/web/src/lib/api.ts`](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/lib/api.ts) (API Client), [`apps/api/app/db.py`](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/db.py) (PostgreSQL), [`apps/api/app/routers/jobs.py`](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/jobs.py) (Job API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_web["Storefront<br/>[page.tsx]"]
  node_wizard["Personalization"]
  node_preview["Preview and Cart<br/>[page.tsx]"]
  node_checkout["Checkout<br/>[page.tsx]"]
  node_webapi["API Client<br/>[api.ts]"]
end

subgraph group_api["API and Commerce"]
  node_catalog["Story Catalog<br/>[stories.py]"]
  node_jobapi["Job API<br/>[jobs.py]"]
  node_orders["Orders<br/>[orders.py]"]
  node_payments["Payments<br/>[payments.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_razorpay["Razorpay"]
end

subgraph group_render["Personalization and Rendering"]
  node_queue["Celery and Redis<br/>[worker.py]"]
  node_tasks["Render Tasks<br/>[tasks.py]"]
  node_personalize["Face Personalization"]
  node_gpu["ComfyUI GPU<br/>[comfyui.py]"]
  node_text["Text Composition<br/>[text_layer.py]"]
end

subgraph group_fulfillment["Fulfillment"]
  node_pdf["PDF Production<br/>[pdf_service.py]"]
end

subgraph group_operations["Administration"]
  node_admin["Admin CMS<br/>[admin.py]"]
  node_settings["Runtime Settings<br/>[app_settings.py]"]
end

node_caregiver(("Caregiver"))

node_caregiver -->|"browses stories"| node_web
node_web -->|"loads catalog"| node_catalog
node_web -->|"starts personalization"| node_wizard
node_wizard -->|"submits photo"| node_webapi
node_webapi -->|"creates render job"| node_jobapi
node_jobapi -->|"stores job"| node_database
node_jobapi -->|"enqueues render"| node_queue
node_queue -->|"runs tasks"| node_tasks
node_tasks -->|"updates progress"| node_database
node_tasks -->|"renders pages"| node_personalize
node_personalize -.->|"requests generation"| node_gpu
node_tasks -->|"composes text"| node_text
node_preview -->|"polls job"| node_webapi
node_preview -->|"continues purchase"| node_checkout
node_checkout -->|"places order"| node_webapi
node_webapi -->|"creates order"| node_orders
node_orders -->|"stores order"| node_database
node_checkout -->|"starts payment"| node_payments
node_payments -->|"creates and verifies"| node_razorpay
node_payments -->|"marks paid"| node_database
node_tasks -->|"stitches book PDF"| node_pdf
node_jobapi -->|"builds downloads"| node_pdf
node_admin -->|"manages catalog"| node_database
node_admin -->|"updates settings"| node_settings

click node_web "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/page.tsx"
click node_wizard "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/components/PersonalizeWizard.tsx"
click node_preview "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/preview/%5BjobId%5D/page.tsx"
click node_checkout "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/checkout/page.tsx"
click node_webapi "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/lib/api.ts"
click node_catalog "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/stories.py"
click node_jobapi "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/jobs.py"
click node_orders "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/orders.py"
click node_payments "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/payments.py"
click node_database "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/db.py"
click node_queue "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/worker.py"
click node_tasks "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/tasks.py"
click node_personalize "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/generation_engine.py"
click node_gpu "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/comfyui.py"
click node_text "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/text_layer.py"
click node_pdf "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/pdf_service.py"
click node_admin "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/admin.py"
click node_settings "https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/app_settings.py"

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_wizard,node_preview,node_checkout,node_webapi toneBlue
class node_catalog,node_jobapi,node_orders,node_payments,node_database,node_razorpay toneAmber
class node_queue,node_tasks,node_personalize,node_gpu,node_text toneMint
class node_pdf toneRose
class node_admin,node_settings,node_caregiver toneIndigo
```

## Components

### Storefront

- [Storefront](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/page.tsx): `apps/web/src/app/(storefront)/page.tsx`
- [Personalization](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/components/PersonalizeWizard.tsx): `apps/web/src/components/PersonalizeWizard.tsx`
- [Preview and Cart](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/preview/%5BjobId%5D/page.tsx): `apps/web/src/app/(storefront)/preview/[jobId]/page.tsx`
- [Checkout](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/app/(storefront)/checkout/page.tsx): `apps/web/src/app/(storefront)/checkout/page.tsx`
- [API Client](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API and Commerce

- [Story Catalog](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/stories.py): `apps/api/app/routers/stories.py`
- [Job API](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/jobs.py): `apps/api/app/routers/jobs.py`
- [Orders](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/orders.py): `apps/api/app/routers/orders.py`
- [Payments](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/payments.py): `apps/api/app/routers/payments.py`
- [PostgreSQL](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/db.py): `apps/api/app/db.py`
- **Razorpay**

### Personalization and Rendering

- [Celery and Redis](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/worker.py): `apps/api/app/worker.py`
- [Render Tasks](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/tasks.py): `apps/api/app/tasks.py`
- [Face Personalization](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/generation_engine.py): `apps/api/app/generation_engine.py`
- [ComfyUI GPU](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/comfyui.py): `apps/api/app/comfyui.py`
- [Text Composition](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/text_layer.py): `apps/api/app/text_layer.py`

### Fulfillment

- [PDF Production](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/pdf_service.py): `apps/api/app/pdf_service.py`

### Administration

- [Admin CMS](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/routers/admin.py): `apps/api/app/routers/admin.py`
- [Runtime Settings](https://github.com/riyazlive04/kuttystorynew/blob/main/apps/api/app/app_settings.py): `apps/api/app/app_settings.py`

### Other components

- **Caregiver**

## Connections

- Caregiver → Storefront: browses stories
- Storefront → Story Catalog: loads catalog
- Storefront → Personalization: starts personalization
- Personalization → API Client: submits photo
- API Client → Job API: creates render job
- Job API → PostgreSQL: stores job (evidence: `apps/api/app/routers/jobs.py`)
- Job API → Celery and Redis: enqueues render
- Celery and Redis → Render Tasks: runs tasks (evidence: `apps/api/app/worker.py`)
- Render Tasks → PostgreSQL: updates progress (evidence: `apps/api/app/tasks.py`)
- Render Tasks → Face Personalization: renders pages (evidence: `apps/api/app/tasks.py`)
- Face Personalization → ComfyUI GPU: requests generation (evidence: `apps/api/app/comfyui.py`)
- Render Tasks → Text Composition: composes text (evidence: `apps/api/app/tasks.py`)
- Preview and Cart → API Client: polls job
- Preview and Cart → Checkout: continues purchase
- Checkout → API Client: places order
- API Client → Orders: creates order
- Orders → PostgreSQL: stores order (evidence: `apps/api/app/routers/orders.py`)
- Checkout → Payments: starts payment
- Payments → Razorpay: creates and verifies
- Payments → PostgreSQL: marks paid (evidence: `apps/api/app/routers/payments.py`)
- Render Tasks → PDF Production: stitches book PDF (evidence: `apps/api/app/tasks.py`)
- Job API → PDF Production: builds downloads (evidence: `apps/api/app/routers/jobs.py`)
- Admin CMS → PostgreSQL: manages catalog (evidence: `apps/api/app/routers/admin.py`)
- Admin CMS → Runtime Settings: updates settings (evidence: `apps/api/app/routers/admin.py`)
