# one-and-done2022/ai-hair-mini-program architecture

> Architecture diagram of the GitHub repository one-and-done2022/ai-hair-mini-program, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/one-and-done2022/ai-hair-mini-program
- Repository: https://github.com/one-and-done2022/ai-hair-mini-program

## Overview

AI Hair Remix is a WeChat mini program backed by a FastAPI service. The main user journey is to sign in, choose a hairstyle or scene (optionally use recommendations or scene understanding), upload a photo, submit a generation job, and poll for previews and results; users can then review history or purchase quota. The backend separates API handling from queued generation and media persistence, with provider routing and operational administration as supporting capabilities. The README also documents internal scene and template review pipelines; their scripts are excluded from this runtime map. Several route and service implementations were not sampled, so uncertain internal links are omitted.

Main entry points: [`backend/app/routers`](https://github.com/one-and-done2022/ai-hair-mini-program/tree/main/backend/app/routers) (Product API routes), [`backend/app/services/repository.py`](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/repository.py) (User and job records), [`miniapp/pages/capture/index.js`](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/capture/index.js) (Photo and style selection), [`backend/app/services/job_queue.py`](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/job_queue.py) (Job worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mini Program"]
  node_miniapp["Mini program<br/>[app.js]"]
  node_creation["Photo and style selection<br/>[index.js]"]
  node_recommend["Recommendations<br/>[index.js]"]
  node_scene_tool["Scene understanding<br/>[index.js]"]
  node_result["Job results<br/>[index.js]"]
  node_history["History<br/>[index.js]"]
  node_purchase_ui["Quota purchase<br/>[index.js]"]
end

subgraph group_api["API and accounts"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_api_routes["Product API routes"]
  node_auth_service["Login service<br/>[auth.py]"]
  node_repository[("User and job records<br/>[repository.py]")]
  node_api_app["FastAPI application<br/>[main.py]"]
end

subgraph group_generation["Generation runtime"]
  node_queue_dispatch["Queue backend<br/>[dispatch_queue.py]"]
  node_job_worker["Job worker<br/>[job_queue.py]"]
  node_generation_service["Image generation<br/>[generation.py]"]
  node_provider_routing["Provider routing"]
  node_storage[("Media storage<br/>[storage.py]")]
end

subgraph group_catalog["Styles and scenes"]
  node_catalog_data["Style catalog<br/>[catalog.py]"]
  node_faceprompt_cli["Catalog CLI<br/>[cli.py]"]
  node_templates["Template service<br/>[templates.py]"]
  node_understanding["Image understanding"]
  node_scene_pipeline["Scene review pipeline<br/>[scene_pipeline.py]"]
end

subgraph group_operations["Operations and billing"]
  node_billing["Payments and quota<br/>[billing.py]"]
  node_provider_admin["Provider administration<br/>[provider_admin.py]"]
  node_admin_console["Admin console<br/>[admin_console.py]"]
end

node_user(("User"))
node_provider{{"Image model provider"}}

node_user -->|"uses"| node_miniapp
node_miniapp -->|"starts creation"| node_creation
node_creation -->|"signs in"| node_auth_api
node_auth_api -->|"authenticates"| node_auth_service
node_auth_service -->|"stores account"| node_repository
node_creation -->|"uploads and submits"| node_api_routes
node_recommend -->|"requests suggestions"| node_api_routes
node_scene_tool -->|"analyzes scene"| node_api_routes
node_api_routes -->|"loads templates"| node_templates
node_api_routes -->|"analyzes image"| node_understanding
node_api_routes -->|"enqueues job"| node_queue_dispatch
node_api_routes -->|"records job"| node_repository
node_api_routes -->|"stores media"| node_storage
node_result -->|"polls job"| node_api_routes
node_result -->|"opens history"| node_history
node_history -->|"loads records"| node_api_routes
node_purchase_ui -->|"purchases quota"| node_api_routes
node_api_routes -->|"handles purchase"| node_billing
node_queue_dispatch -->|"dispatches jobs"| node_job_worker
node_job_worker -->|"loads and updates"| node_repository
node_job_worker -->|"generates images"| node_generation_service
node_generation_service -->|"selects provider"| node_provider_routing
node_generation_service -->|"saves results"| node_storage
node_provider_routing -->|"calls model"| node_provider
node_faceprompt_cli -->|"reads catalog"| node_catalog_data
node_templates -.->|"uses style records"| node_catalog_data
node_scene_pipeline -->|"extracts scene blocks"| node_understanding
node_provider_admin -->|"configures routing"| node_provider_routing
node_admin_console -->|"manages records"| node_repository

click node_miniapp "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/app.js"
click node_creation "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/capture/index.js"
click node_recommend "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/recommend/index.js"
click node_scene_tool "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/scene-tool/index.js"
click node_result "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/result/index.js"
click node_history "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/history/index.js"
click node_purchase_ui "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/payment/index.js"
click node_auth_api "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/auth.py"
click node_api_routes "https://github.com/one-and-done2022/ai-hair-mini-program/tree/main/backend/app/routers"
click node_auth_service "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/auth.py"
click node_repository "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/repository.py"
click node_catalog_data "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/Faceprompt/src/faceprompt/catalog.py"
click node_faceprompt_cli "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/Faceprompt/src/faceprompt/cli.py"
click node_templates "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/templates.py"
click node_understanding "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/image_understanding.py"
click node_api_app "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/main.py"
click node_queue_dispatch "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/dispatch_queue.py"
click node_job_worker "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/job_queue.py"
click node_generation_service "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/generation.py"
click node_provider_routing "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/provider_routing.py"
click node_storage "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/storage.py"
click node_billing "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/billing.py"
click node_provider_admin "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/provider_admin.py"
click node_scene_pipeline "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/scripts/scene_pipeline.py"
click node_admin_console "https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/admin_console.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_miniapp,node_creation,node_recommend,node_scene_tool,node_result,node_history,node_purchase_ui,node_user toneBlue
class node_auth_api,node_api_routes,node_auth_service,node_repository,node_api_app toneAmber
class node_queue_dispatch,node_job_worker,node_generation_service,node_provider_routing,node_storage toneMint
class node_catalog_data,node_faceprompt_cli,node_templates,node_understanding,node_scene_pipeline toneRose
class node_billing,node_provider_admin,node_admin_console,node_provider toneIndigo
```

## Components

### Mini Program

- [Mini program](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/app.js): `miniapp/app.js`
- [Photo and style selection](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/capture/index.js): `miniapp/pages/capture/index.js`
- [Recommendations](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/recommend/index.js): `miniapp/pages/recommend/index.js`
- [Scene understanding](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/scene-tool/index.js): `miniapp/pages/scene-tool/index.js`
- [Job results](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/result/index.js): `miniapp/pages/result/index.js`
- [History](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/history/index.js): `miniapp/pages/history/index.js`
- [Quota purchase](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/miniapp/pages/payment/index.js): `miniapp/pages/payment/index.js`

### API and accounts

- [Authentication API](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Product API routes](https://github.com/one-and-done2022/ai-hair-mini-program/tree/main/backend/app/routers): `backend/app/routers`
- [Login service](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`
- [User and job records](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/repository.py): `backend/app/services/repository.py`
- [FastAPI application](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/main.py): `backend/app/main.py`

### Generation runtime

- [Queue backend](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/dispatch_queue.py): `backend/app/services/dispatch_queue.py`
- [Job worker](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/job_queue.py): `backend/app/services/job_queue.py`
- [Image generation](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/generation.py): `backend/app/services/generation.py`
- [Provider routing](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/provider_routing.py): `backend/app/services/provider_routing.py`
- [Media storage](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`

### Styles and scenes

- [Style catalog](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/Faceprompt/src/faceprompt/catalog.py): `Faceprompt/src/faceprompt/catalog.py`
- [Catalog CLI](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/Faceprompt/src/faceprompt/cli.py): `Faceprompt/src/faceprompt/cli.py`
- [Template service](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/templates.py): `backend/app/services/templates.py`
- [Image understanding](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/image_understanding.py): `backend/app/services/image_understanding.py`
- [Scene review pipeline](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/scripts/scene_pipeline.py): `scripts/scene_pipeline.py`

### Operations and billing

- [Payments and quota](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/services/billing.py): `backend/app/services/billing.py`
- [Provider administration](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/provider_admin.py): `backend/app/routers/provider_admin.py`
- [Admin console](https://github.com/one-and-done2022/ai-hair-mini-program/blob/main/backend/app/routers/admin_console.py): `backend/app/routers/admin_console.py`

### Other components

- **User**
- **Image model provider**

## Connections

- User → Mini program: uses
- Mini program → Photo and style selection: starts creation
- Photo and style selection → Authentication API: signs in
- Authentication API → Login service: authenticates
- Login service → User and job records: stores account
- Photo and style selection → Product API routes: uploads and submits
- Recommendations → Product API routes: requests suggestions
- Scene understanding → Product API routes: analyzes scene
- Product API routes → Template service: loads templates
- Product API routes → Image understanding: analyzes image
- Product API routes → Queue backend: enqueues job
- Product API routes → User and job records: records job
- Product API routes → Media storage: stores media
- Job results → Product API routes: polls job
- Job results → History: opens history
- History → Product API routes: loads records
- Quota purchase → Product API routes: purchases quota
- Product API routes → Payments and quota: handles purchase
- Queue backend → Job worker: dispatches jobs
- Job worker → User and job records: loads and updates
- Job worker → Image generation: generates images
- Image generation → Provider routing: selects provider
- Image generation → Media storage: saves results
- Provider routing → Image model provider: calls model
- Catalog CLI → Style catalog: reads catalog
- Template service → Style catalog: uses style records
- Scene review pipeline → Image understanding: extracts scene blocks
- Provider administration → Provider routing: configures routing
- Admin console → User and job records: manages records