# innovat3x/brand-intelligence architecture

> Architecture diagram of the GitHub repository innovat3x/brand-intelligence, 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/innovat3x/brand-intelligence
- Repository: https://github.com/innovat3x/brand-intelligence

## Overview

Brand Intelligence is an AI-assisted workspace that guides a product idea through discovery, positioning, brand shaping, visual identity, challenge, and a compiled brand kit. Users create and revisit projects, submit stage inputs, and review or edit accumulated brand state; they can also export project details and workflow history. The frontend hooks and API client are sampled, as are project, brand, export, and database services. Backend route-to-service wiring and detailed workflow orchestration are not shown, so those connections are omitted rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/main.py) (FastAPI application), [`frontend/app/project/[id]/page.tsx`](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/app/project/%5Bid%5D/page.tsx) (Project workspace), [`frontend/lib/api.ts`](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/lib/api.ts) (API client), [`backend/app/models/brand_state.py`](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/models/brand_state.py) (Persistence models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web app<br/>[page.tsx]"]
  node_project_pages["Project workspace<br/>[page.tsx]"]
  node_workflow_hook["Workflow hook<br/>[useWorkflow.ts]"]
  node_brand_hook["Brand hook<br/>[useBrandKit.ts]"]
  node_project_hook["Project hook<br/>[useProject.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_stages["Brand workflow"]
  node_discovery["Discovery<br/>[discovery.py]"]
  node_positioning["Positioning<br/>[positioning.py]"]
  node_brand_shape["Brand shaping<br/>[naming.py]"]
  node_brand_personality["Personality and voice<br/>[personality.py]"]
  node_visual_identity["Visual identity<br/>[visualize.py]"]
  node_challenge["Brand challenge<br/>[challenge.py]"]
  node_brand_kit["Brand kit<br/>[deliver.py]"]
end

subgraph group_backend["Backend services"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_project_api["Project API<br/>[projects.py]"]
  node_workflow_api["Workflow API<br/>[workflow.py]"]
  node_brand_api["Brand API<br/>[brand.py]"]
  node_export_api["Export API<br/>[export.py]"]
  node_project_service["Project service<br/>[project_service.py]"]
  node_brand_service["Brand service<br/>[brand_service.py]"]
  node_export_service["Export service<br/>[export_service.py]"]
  node_workflow_engine["Workflow engine<br/>[graph.py]"]
end

subgraph group_state["Project state"]
  node_models["Persistence models<br/>[brand_state.py]"]
  node_database[("Database<br/>[database.py]")]
end

node_user(("Brand creator"))

node_user -->|"uses"| node_web
node_web -->|"opens projects"| node_project_pages
node_project_pages -->|"loads project"| node_project_hook
node_project_pages -->|"starts stages"| node_workflow_hook
node_project_pages -->|"loads brand"| node_brand_hook
node_project_hook -->|"requests project"| node_api_client
node_workflow_hook -->|"starts and lists runs"| node_api_client
node_brand_hook -->|"reads and saves"| node_api_client
node_api_client -->|"HTTP requests"| node_backend_app
node_backend_app -->|"dispatches"| node_project_api
node_backend_app -->|"dispatches"| node_workflow_api
node_backend_app -->|"dispatches"| node_brand_api
node_backend_app -->|"dispatches"| node_export_api
node_project_service -->|"reads and writes"| node_database
node_brand_service -->|"reads and writes"| node_database
node_export_service -->|"reads"| node_database
node_project_service -->|"persists project"| node_models
node_brand_service -->|"persists brand state"| node_models
node_export_service -->|"reads state"| node_models

click node_web "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/app/page.tsx"
click node_project_pages "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/app/project/%5Bid%5D/page.tsx"
click node_workflow_hook "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useWorkflow.ts"
click node_brand_hook "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useBrandKit.ts"
click node_project_hook "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useProject.ts"
click node_api_client "https://github.com/innovat3x/brand-intelligence/blob/main/frontend/lib/api.ts"
click node_discovery "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/discovery.py"
click node_positioning "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/positioning.py"
click node_brand_shape "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/naming.py"
click node_brand_personality "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/personality.py"
click node_visual_identity "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/visualize.py"
click node_challenge "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/challenge.py"
click node_brand_kit "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/deliver.py"
click node_backend_app "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/main.py"
click node_project_api "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/projects.py"
click node_workflow_api "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/workflow.py"
click node_brand_api "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/brand.py"
click node_export_api "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/export.py"
click node_project_service "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/project_service.py"
click node_brand_service "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/brand_service.py"
click node_export_service "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/export_service.py"
click node_workflow_engine "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/workflow/graph.py"
click node_models "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/models/brand_state.py"
click node_database "https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/database.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_project_pages,node_workflow_hook,node_brand_hook,node_project_hook,node_api_client toneBlue
class node_discovery,node_positioning,node_brand_shape,node_brand_personality,node_visual_identity,node_challenge,node_brand_kit toneAmber
class node_backend_app,node_project_api,node_workflow_api,node_brand_api,node_export_api,node_project_service,node_brand_service,node_export_service,node_workflow_engine toneMint
class node_models,node_database toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Project workspace](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/app/project/%5Bid%5D/page.tsx): `frontend/app/project/[id]/page.tsx`
- [Workflow hook](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useWorkflow.ts): `frontend/hooks/useWorkflow.ts`
- [Brand hook](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useBrandKit.ts): `frontend/hooks/useBrandKit.ts`
- [Project hook](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/hooks/useProject.ts): `frontend/hooks/useProject.ts`
- [API client](https://github.com/innovat3x/brand-intelligence/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Brand workflow

- [Discovery](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/discovery.py): `backend/app/agents/discovery.py`
- [Positioning](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/positioning.py): `backend/app/agents/positioning.py`
- [Brand shaping](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/naming.py): `backend/app/agents/naming.py`
- [Personality and voice](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/personality.py): `backend/app/agents/personality.py`
- [Visual identity](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/visualize.py): `backend/app/agents/visualize.py`
- [Brand challenge](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/challenge.py): `backend/app/agents/challenge.py`
- [Brand kit](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/agents/deliver.py): `backend/app/agents/deliver.py`

### Backend services

- [FastAPI application](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project API](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Workflow API](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/workflow.py): `backend/app/api/workflow.py`
- [Brand API](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/brand.py): `backend/app/api/brand.py`
- [Export API](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/api/export.py): `backend/app/api/export.py`
- [Project service](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/project_service.py): `backend/app/services/project_service.py`
- [Brand service](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/brand_service.py): `backend/app/services/brand_service.py`
- [Export service](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/export_service.py): `backend/app/services/export_service.py`
- [Workflow engine](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/workflow/graph.py): `backend/app/workflow/graph.py`

### Project state

- [Persistence models](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/models/brand_state.py): `backend/app/models/brand_state.py`
- [Database](https://github.com/innovat3x/brand-intelligence/blob/main/backend/app/services/database.py): `backend/app/services/database.py`

### Other components

- **Brand creator**

## Connections

- Brand creator → Web app: uses
- Web app → Project workspace: opens projects
- Project workspace → Project hook: loads project
- Project workspace → Workflow hook: starts stages
- Project workspace → Brand hook: loads brand
- Project hook → API client: requests project
- Workflow hook → API client: starts and lists runs
- Brand hook → API client: reads and saves
- API client → FastAPI application: HTTP requests
- FastAPI application → Project API: dispatches
- FastAPI application → Workflow API: dispatches
- FastAPI application → Brand API: dispatches
- FastAPI application → Export API: dispatches
- Project service → Database: reads and writes
- Brand service → Database: reads and writes
- Export service → Database: reads
- Project service → Persistence models: persists project
- Brand service → Persistence models: persists brand state
- Export service → Persistence models: reads state