# dzuy/substrate architecture

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

- Interactive diagram: https://gitdiagram.com/dzuy/substrate
- Repository: https://github.com/dzuy/substrate

## Overview

Substrate is a mobile-first skincare intelligence app. The main user journey captures daily check-ins and photos, combines those inputs with profile and environmental context, then presents a Skin Story and a checklist-style daily plan. Users can also manage a product wardrobe and track progress; administrators manage the product catalog and users, and can ask Tate questions about catalog data. The README documents the major capabilities, while source excerpts and the index support only some implementation links; unverified subsystem relationships are omitted.

Main entry points: [`src/app`](https://github.com/dzuy/substrate/tree/main/src/app) (App screens), [`src/lib/supabase.ts`](https://github.com/dzuy/substrate/blob/main/src/lib/supabase.ts) (Supabase client), [`prototypes/face-scan/handler.mjs`](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/handler.mjs) (Face Scan handler), [`src/services/catalog.ts`](https://github.com/dzuy/substrate/blob/main/src/services/catalog.ts) (Product catalog service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Skincare app"]
  node_app_screens["App screens"]
  node_auth_ui["Sign-in screen<br/>[auth-screen.tsx]"]
  node_auth_context["Session context<br/>[auth-context.tsx]"]
  node_auth_service["Authentication<br/>[auth.ts]"]
  node_data_services["Daily data services"]
  node_database_types["Data model<br/>[database.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_supabase[("Supabase")]
end

subgraph group_intelligence["Skin intelligence"]
  node_photo_analysis["Photo analysis<br/>[index.ts]"]
  node_product_analysis["Product analysis<br/>[index.ts]"]
  node_story_engine["Skin Story engine<br/>[skinStoryEngine.ts]"]
  node_story_rules["Story rules<br/>[skinStoryRules.ts]"]
  node_plan_engine["Today Plan engine<br/>[todayPlanEngine.ts]"]
  node_recommendations["Recommendations<br/>[recommendations.ts]"]
  node_progress_summary["Progress summary<br/>[index.ts]"]
  node_recommendation_function["Recommendation function<br/>[index.ts]"]
end

subgraph group_catalog["Product catalog"]
  node_wardrobe["Skin Wardrobe<br/>[skin-wardrobe.tsx]"]
  node_catalog_service["Product catalog service<br/>[catalog.ts]"]
  node_catalog_cms["Catalog CMS service<br/>[catalog-cms.ts]"]
  node_catalog_pagination["Catalog pagination"]
end

subgraph group_admin["Administration"]
  node_catalog_ui["Catalog workspace"]
  node_admin_users["User administration<br/>[admin-users.ts]"]
  node_ask_drawer["Ask Tate drawer"]
  node_ask_server["Ask Tate server<br/>[ask-tate.mjs]"]
  node_production_server["Production server<br/>[production.mjs]"]
end

subgraph group_lab["Face Scan Lab"]
  node_face_lab_ui["Face Scan Lab UI<br/>[app.js]"]
  node_face_lab_handler["Face Scan handler<br/>[handler.mjs]"]
  node_face_providers["Analysis providers<br/>[providers.mjs]"]
  node_face_questions["Assessment questions<br/>[questions.mjs]"]
  node_face_catalog["Lab catalog lookup<br/>[database.mjs]"]
end

node_user(("User"))
node_admin_actor(("Administrator"))
node_openai{{"OpenAI"}}

node_user -->|"signs in"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_auth_service
node_auth_context -->|"reads session"| node_supabase_client
node_auth_service -->|"authenticates"| node_supabase_client
node_user -->|"uses"| node_app_screens
node_app_screens -.->|"records daily inputs"| node_data_services
node_data_services -.->|"reads and writes"| node_supabase_client
node_supabase_client -->|"connects to"| node_supabase
node_app_screens -.->|"requests photo analysis"| node_photo_analysis
node_app_screens -.->|"produces Skin Story"| node_story_engine
node_story_engine -->|"uses rules"| node_story_rules
node_app_screens -.->|"generates daily checklist"| node_plan_engine
node_plan_engine -->|"uses state labels"| node_story_rules
node_app_screens -.->|"loads recommendations"| node_recommendations
node_recommendations -->|"uses engine"| node_story_engine
node_recommendations -->|"uses engine"| node_plan_engine
node_recommendations -->|"reads and writes"| node_supabase_client
node_app_screens -.->|"requests progress summary"| node_progress_summary
node_app_screens -.->|"requests recommendation"| node_recommendation_function
node_user -->|"manages products"| node_wardrobe
node_wardrobe -->|"loads catalog"| node_catalog_service
node_catalog_service -->|"collects pages"| node_catalog_pagination
node_catalog_service -->|"queries catalog"| node_supabase_client
node_admin_actor -->|"manages catalog"| node_catalog_ui
node_catalog_ui -->|"loads product data"| node_catalog_service
node_catalog_ui -->|"loads and saves CMS data"| node_catalog_cms
node_catalog_cms -->|"uses catalog service"| node_catalog_service
node_admin_actor -->|"manages accounts"| node_admin_users
node_admin_actor -->|"asks catalog questions"| node_ask_drawer
node_ask_drawer -->|"sends chat request"| node_ask_server
node_ask_server -->|"retrieves catalog records"| node_supabase
node_ask_server -->|"generates answers"| node_openai
node_production_server -->|"routes requests"| node_ask_server
node_user -->|"tries lab prototype"| node_face_lab_ui
node_face_lab_ui -.->|"submits analysis"| node_face_lab_handler
node_face_lab_handler -->|"creates providers"| node_face_providers
node_face_lab_handler -->|"uses assessment questions"| node_face_questions
node_face_lab_handler -->|"loads catalog"| node_face_catalog
node_production_server -->|"routes requests"| node_face_lab_handler
node_face_providers -.->|"uses AI provider"| node_openai

click node_app_screens "https://github.com/dzuy/substrate/tree/main/src/app"
click node_auth_ui "https://github.com/dzuy/substrate/blob/main/src/components/auth-screen.tsx"
click node_auth_context "https://github.com/dzuy/substrate/blob/main/src/lib/auth-context.tsx"
click node_auth_service "https://github.com/dzuy/substrate/blob/main/src/services/auth.ts"
click node_data_services "https://github.com/dzuy/substrate/tree/main/src/services"
click node_database_types "https://github.com/dzuy/substrate/blob/main/src/types/database.ts"
click node_supabase_client "https://github.com/dzuy/substrate/blob/main/src/lib/supabase.ts"
click node_photo_analysis "https://github.com/dzuy/substrate/blob/main/supabase/functions/analyze-photo/index.ts"
click node_product_analysis "https://github.com/dzuy/substrate/blob/main/supabase/functions/analyze-products/index.ts"
click node_story_engine "https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/skinStoryEngine.ts"
click node_story_rules "https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/skinStoryRules.ts"
click node_plan_engine "https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/todayPlanEngine.ts"
click node_recommendations "https://github.com/dzuy/substrate/blob/main/src/services/recommendations.ts"
click node_progress_summary "https://github.com/dzuy/substrate/blob/main/supabase/functions/generate-progress-summary/index.ts"
click node_recommendation_function "https://github.com/dzuy/substrate/blob/main/supabase/functions/generate-recommendation/index.ts"
click node_wardrobe "https://github.com/dzuy/substrate/blob/main/src/app/skin-wardrobe.tsx"
click node_catalog_service "https://github.com/dzuy/substrate/blob/main/src/services/catalog.ts"
click node_catalog_cms "https://github.com/dzuy/substrate/blob/main/src/services/catalog-cms.ts"
click node_catalog_pagination "https://github.com/dzuy/substrate/blob/main/src/services/catalog-pagination.ts"
click node_catalog_ui "https://github.com/dzuy/substrate/blob/main/src/components/admin/catalog-workspace.tsx"
click node_admin_users "https://github.com/dzuy/substrate/blob/main/src/services/admin-users.ts"
click node_ask_drawer "https://github.com/dzuy/substrate/blob/main/src/components/admin/ask-tate-drawer.tsx"
click node_ask_server "https://github.com/dzuy/substrate/blob/main/server/ask-tate.mjs"
click node_production_server "https://github.com/dzuy/substrate/blob/main/server/production.mjs"
click node_face_lab_ui "https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/public/app.js"
click node_face_lab_handler "https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/handler.mjs"
click node_face_providers "https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/providers.mjs"
click node_face_questions "https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/public/questions.mjs"
click node_face_catalog "https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/catalog/database.mjs"

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_app_screens,node_auth_ui,node_auth_context,node_auth_service,node_data_services,node_database_types,node_supabase_client,node_supabase,node_user toneBlue
class node_photo_analysis,node_product_analysis,node_story_engine,node_story_rules,node_plan_engine,node_recommendations,node_progress_summary,node_recommendation_function toneAmber
class node_wardrobe,node_catalog_service,node_catalog_cms,node_catalog_pagination toneMint
class node_catalog_ui,node_admin_users,node_ask_drawer,node_ask_server,node_production_server toneRose
class node_face_lab_ui,node_face_lab_handler,node_face_providers,node_face_questions,node_face_catalog,node_admin_actor,node_openai toneIndigo
```

## Components

### Skincare app

- [App screens](https://github.com/dzuy/substrate/tree/main/src/app): `src/app`
- [Sign-in screen](https://github.com/dzuy/substrate/blob/main/src/components/auth-screen.tsx): `src/components/auth-screen.tsx`
- [Session context](https://github.com/dzuy/substrate/blob/main/src/lib/auth-context.tsx): `src/lib/auth-context.tsx`
- [Authentication](https://github.com/dzuy/substrate/blob/main/src/services/auth.ts): `src/services/auth.ts`
- [Daily data services](https://github.com/dzuy/substrate/tree/main/src/services): `src/services`
- [Data model](https://github.com/dzuy/substrate/blob/main/src/types/database.ts): `src/types/database.ts`
- [Supabase client](https://github.com/dzuy/substrate/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- **Supabase**

### Skin intelligence

- [Photo analysis](https://github.com/dzuy/substrate/blob/main/supabase/functions/analyze-photo/index.ts): `supabase/functions/analyze-photo/index.ts`
- [Product analysis](https://github.com/dzuy/substrate/blob/main/supabase/functions/analyze-products/index.ts): `supabase/functions/analyze-products/index.ts`
- [Skin Story engine](https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/skinStoryEngine.ts): `src/skin-intelligence/skinStoryEngine.ts`
- [Story rules](https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/skinStoryRules.ts): `src/skin-intelligence/skinStoryRules.ts`
- [Today Plan engine](https://github.com/dzuy/substrate/blob/main/src/skin-intelligence/todayPlanEngine.ts): `src/skin-intelligence/todayPlanEngine.ts`
- [Recommendations](https://github.com/dzuy/substrate/blob/main/src/services/recommendations.ts): `src/services/recommendations.ts`
- [Progress summary](https://github.com/dzuy/substrate/blob/main/supabase/functions/generate-progress-summary/index.ts): `supabase/functions/generate-progress-summary/index.ts`
- [Recommendation function](https://github.com/dzuy/substrate/blob/main/supabase/functions/generate-recommendation/index.ts): `supabase/functions/generate-recommendation/index.ts`

### Product catalog

- [Skin Wardrobe](https://github.com/dzuy/substrate/blob/main/src/app/skin-wardrobe.tsx): `src/app/skin-wardrobe.tsx`
- [Product catalog service](https://github.com/dzuy/substrate/blob/main/src/services/catalog.ts): `src/services/catalog.ts`
- [Catalog CMS service](https://github.com/dzuy/substrate/blob/main/src/services/catalog-cms.ts): `src/services/catalog-cms.ts`
- [Catalog pagination](https://github.com/dzuy/substrate/blob/main/src/services/catalog-pagination.ts): `src/services/catalog-pagination.ts`

### Administration

- [Catalog workspace](https://github.com/dzuy/substrate/blob/main/src/components/admin/catalog-workspace.tsx): `src/components/admin/catalog-workspace.tsx`
- [User administration](https://github.com/dzuy/substrate/blob/main/src/services/admin-users.ts): `src/services/admin-users.ts`
- [Ask Tate drawer](https://github.com/dzuy/substrate/blob/main/src/components/admin/ask-tate-drawer.tsx): `src/components/admin/ask-tate-drawer.tsx`
- [Ask Tate server](https://github.com/dzuy/substrate/blob/main/server/ask-tate.mjs): `server/ask-tate.mjs`
- [Production server](https://github.com/dzuy/substrate/blob/main/server/production.mjs): `server/production.mjs`

### Face Scan Lab

- [Face Scan Lab UI](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/public/app.js): `prototypes/face-scan/public/app.js`
- [Face Scan handler](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/handler.mjs): `prototypes/face-scan/handler.mjs`
- [Analysis providers](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/providers.mjs): `prototypes/face-scan/providers.mjs`
- [Assessment questions](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/public/questions.mjs): `prototypes/face-scan/public/questions.mjs`
- [Lab catalog lookup](https://github.com/dzuy/substrate/blob/main/prototypes/face-scan/catalog/database.mjs): `prototypes/face-scan/catalog/database.mjs`

### Other components

- **User**
- **Administrator**
- **OpenAI**

## Connections

- User → Sign-in screen: signs in (evidence: `src/components/auth-screen.tsx`)
- Sign-in screen → Authentication: submits credentials (evidence: `src/components/auth-screen.tsx`)
- Session context → Supabase client: reads session (evidence: `src/lib/auth-context.tsx`)
- Authentication → Supabase client: authenticates (evidence: `src/services/auth.ts`)
- User → App screens: uses (evidence: `README.md`)
- App screens → Daily data services: records daily inputs (evidence: `src/app/index.tsx`)
- Daily data services → Supabase client: reads and writes (evidence: `src/services/auth.ts`)
- Supabase client → Supabase: connects to (evidence: `README.md`)
- App screens → Photo analysis: requests photo analysis
- App screens → Skin Story engine: produces Skin Story
- Skin Story engine → Story rules: uses rules (evidence: `src/skin-intelligence/skinStoryEngine.ts`)
- App screens → Today Plan engine: generates daily checklist
- Today Plan engine → Story rules: uses state labels (evidence: `src/skin-intelligence/todayPlanEngine.ts`)
- App screens → Recommendations: loads recommendations
- Recommendations → Skin Story engine: uses engine (evidence: `src/services/recommendations.ts`)
- Recommendations → Today Plan engine: uses engine (evidence: `src/services/recommendations.ts`)
- Recommendations → Supabase client: reads and writes (evidence: `src/services/recommendations.ts`)
- App screens → Progress summary: requests progress summary
- App screens → Recommendation function: requests recommendation
- User → Skin Wardrobe: manages products (evidence: `README.md`)
- Skin Wardrobe → Product catalog service: loads catalog (evidence: `src/app/skin-wardrobe.tsx`)
- Product catalog service → Catalog pagination: collects pages (evidence: `src/services/catalog.ts`)
- Product catalog service → Supabase client: queries catalog (evidence: `src/services/catalog.ts`)
- Administrator → Catalog workspace: manages catalog (evidence: `README.md`)
- Catalog workspace → Product catalog service: loads product data (evidence: `src/components/admin/catalog-workspace.tsx`)
- Catalog workspace → Catalog CMS service: loads and saves CMS data (evidence: `src/components/admin/catalog-workspace.tsx`)
- Catalog CMS service → Product catalog service: uses catalog service (evidence: `src/services/catalog-cms.ts`)
- Administrator → User administration: manages accounts (evidence: `README.md`)
- Administrator → Ask Tate drawer: asks catalog questions (evidence: `README.md`)
- Ask Tate drawer → Ask Tate server: sends chat request (evidence: `README.md`)
- Ask Tate server → Supabase: retrieves catalog records (evidence: `README.md`)
- Ask Tate server → OpenAI: generates answers (evidence: `README.md`)
- Production server → Ask Tate server: routes requests (evidence: `server/production.mjs`)
- User → Face Scan Lab UI: tries lab prototype (evidence: `README.md`)
- Face Scan Lab UI → Face Scan handler: submits analysis
- Face Scan handler → Analysis providers: creates providers (evidence: `prototypes/face-scan/handler.mjs`)
- Face Scan handler → Assessment questions: uses assessment questions (evidence: `prototypes/face-scan/handler.mjs`)
- Face Scan handler → Lab catalog lookup: loads catalog (evidence: `prototypes/face-scan/handler.mjs`)
- Production server → Face Scan handler: routes requests (evidence: `server/production.mjs`)
- Analysis providers → OpenAI: uses AI provider
