# harolducon-omc/categorizaromc architecture

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

- Interactive diagram: https://gitdiagram.com/harolducon-omc/categorizaromc
- Repository: https://github.com/harolducon-omc/categorizaromc

## Overview

Insights Studio is a React/FastAPI research platform for uploading survey data, categorizing open-ended answers, reviewing results and exporting reports; it also provides standalone and study-integrated Awareness analysis. The main workflow runs from authenticated study upload through question-level categorization and review to frequencies, segment comparisons, insights and Excel export. PostgreSQL persists studies and results. The README documents capabilities whose implementation was not sampled; those branches are shown as documented, with source-level evidence limits kept explicit.

Main entry points: [`backend/app/routers/classifications.py`](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/classifications.py) (Classification routes), [`backend/app/main.py`](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/api.ts`](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/App.tsx) (Insights Studio UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_webapp["Insights Studio UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_ui["Sign-in screen<br/>[AuthPage.tsx]"]
  node_categorize_ui["Categorization workflow"]
  node_dashboard_ui["Dashboard review<br/>[DashboardPage.tsx]"]
  node_integrated_awareness_ui["Study Awareness UI"]
end

subgraph group_accounts["Accounts and policy"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_account_rules["Account management<br/>[accounts.py]"]
  node_security["Security policies<br/>[policies.py]"]
end

subgraph group_studies["Studies and storage"]
  node_study_routes["Study routes<br/>[studies.py]"]
  node_study_service["Import and study service<br/>[services.py]"]
  node_database[("PostgreSQL")]
end

subgraph group_analysis["Classification and insights"]
  node_classification_routes["Classification routes<br/>[classifications.py]"]
  node_coding["Open-answer coding<br/>[coding.py]"]
  node_brand_catalog["Brand catalog<br/>[brands.py]"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_quality["Quality review<br/>[quality.py]"]
  node_insights["Insights and segments<br/>[insights.py]"]
  node_exports["Excel exports<br/>[export.py]"]
end

subgraph group_awareness["Awareness analysis"]
  node_awareness_ui["Standalone Awareness UI"]
  node_awareness_routes["Standalone Awareness routes<br/>[awareness_flex.py]"]
  node_awareness_flex["Flexible Awareness engine<br/>[awareness_flex.py]"]
  node_awareness_core["Awareness calculations<br/>[awareness.py]"]
  node_integrated_awareness_routes["Study Awareness routes<br/>[study_awareness.py]"]
end

subgraph group_support["Help and administration"]
  node_help["Help assistant<br/>[help_assistant.py]"]
  node_help_kb["Help knowledge base<br/>[help_kb.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_api_entry["FastAPI application<br/>[main.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_webapp
node_webapp -->|"opens"| node_auth_ui
node_webapp -->|"calls"| node_api_client
node_auth_ui -->|"submits credentials"| node_api_client
node_categorize_ui -.->|"requests operations"| node_api_client
node_dashboard_ui -->|"requests results"| node_api_client
node_integrated_awareness_ui -->|"requests analysis"| node_api_client
node_api_client -->|"sends HTTP requests"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_study_routes
node_api_entry -->|"registers"| node_classification_routes
node_api_entry -->|"registers"| node_integrated_awareness_routes
node_api_entry -->|"registers"| node_awareness_routes
node_api_entry -->|"registers"| node_admin_routes
node_auth_routes -->|"uses"| node_account_rules
node_auth_routes -->|"checks policy"| node_security
node_study_routes -->|"creates studies"| node_study_service
node_study_service -->|"persists rows"| node_database
node_classification_routes -->|"classifies responses"| node_coding
node_classification_routes -->|"saves results"| node_database
node_classification_routes -->|"uses catalog"| node_brand_catalog
node_coding -->|"requests completion"| node_llm
node_classification_routes -.->|"provides quality review"| node_quality
node_classification_routes -.->|"provides insights"| node_insights
node_classification_routes -.->|"provides exports"| node_exports
node_awareness_ui -.->|"uses service"| node_awareness_routes
node_awareness_routes -.->|"runs analysis"| node_awareness_flex
node_awareness_flex -->|"uses calculations"| node_awareness_core
node_integrated_awareness_routes -.->|"uses calculations"| node_awareness_core
node_webapp -.->|"offers assistant"| node_help
node_help -.->|"uses knowledge"| node_help_kb
node_admin_routes -->|"manages policy"| node_security
node_llm -.->|"calls AI providers"| node_researcher

click node_webapp "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/api.ts"
click node_auth_ui "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/AuthPage.tsx"
click node_categorize_ui "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/CategorizeWorkflow.tsx"
click node_dashboard_ui "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_integrated_awareness_ui "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/AwarenessIntegrated.tsx"
click node_auth_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/auth.py"
click node_account_rules "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/accounts.py"
click node_security "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/policies.py"
click node_study_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/studies.py"
click node_study_service "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/services.py"
click node_classification_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/classifications.py"
click node_coding "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/coding.py"
click node_brand_catalog "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/brands.py"
click node_llm "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/llm.py"
click node_quality "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/quality.py"
click node_insights "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/insights.py"
click node_exports "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/export.py"
click node_awareness_ui "https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/AwarenessStandalone.tsx"
click node_awareness_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/awareness_flex.py"
click node_awareness_flex "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/awareness_flex.py"
click node_awareness_core "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/awareness.py"
click node_integrated_awareness_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/study_awareness.py"
click node_help "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/help_assistant.py"
click node_help_kb "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/help_kb.py"
click node_admin_routes "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/admin.py"
click node_api_entry "https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/main.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_webapp,node_api_client,node_auth_ui,node_categorize_ui,node_dashboard_ui,node_integrated_awareness_ui toneBlue
class node_auth_routes,node_account_rules,node_security toneAmber
class node_study_routes,node_study_service,node_database toneMint
class node_classification_routes,node_coding,node_brand_catalog,node_llm,node_quality,node_insights,node_exports toneRose
class node_awareness_ui,node_awareness_routes,node_awareness_flex,node_awareness_core,node_integrated_awareness_routes,node_researcher toneIndigo
class node_help,node_help_kb,node_admin_routes,node_api_entry toneTeal
```

## Components

### User interface

- [Insights Studio UI](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Sign-in screen](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/AuthPage.tsx): `frontend/src/pages/AuthPage.tsx`
- [Categorization workflow](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/CategorizeWorkflow.tsx): `frontend/src/CategorizeWorkflow.tsx`
- [Dashboard review](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Study Awareness UI](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/pages/AwarenessIntegrated.tsx): `frontend/src/pages/AwarenessIntegrated.tsx`

### Accounts and policy

- [Authentication routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Account management](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/accounts.py): `backend/app/accounts.py`
- [Security policies](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/policies.py): `backend/app/policies.py`

### Studies and storage

- [Study routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/studies.py): `backend/app/routers/studies.py`
- [Import and study service](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/services.py): `backend/app/services.py`
- **PostgreSQL**

### Classification and insights

- [Classification routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/classifications.py): `backend/app/routers/classifications.py`
- [Open-answer coding](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/coding.py): `backend/core/coding.py`
- [Brand catalog](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/brands.py): `backend/core/brands.py`
- [LLM providers](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/llm.py): `backend/core/llm.py`
- [Quality review](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/quality.py): `backend/core/quality.py`
- [Insights and segments](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/insights.py): `backend/core/insights.py`
- [Excel exports](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/export.py): `backend/core/export.py`

### Awareness analysis

- [Standalone Awareness UI](https://github.com/harolducon-omc/categorizaromc/blob/main/frontend/src/AwarenessStandalone.tsx): `frontend/src/AwarenessStandalone.tsx`
- [Standalone Awareness routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/awareness_flex.py): `backend/app/awareness_flex.py`
- [Flexible Awareness engine](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/awareness_flex.py): `backend/core/awareness_flex.py`
- [Awareness calculations](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/awareness.py): `backend/core/awareness.py`
- [Study Awareness routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/study_awareness.py): `backend/app/routers/study_awareness.py`

### Help and administration

- [Help assistant](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/help_assistant.py): `backend/core/help_assistant.py`
- [Help knowledge base](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/core/help_kb.py): `backend/core/help_kb.py`
- [Admin routes](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [FastAPI application](https://github.com/harolducon-omc/categorizaromc/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Researcher**

## Connections

- Researcher → Insights Studio UI: uses
- Insights Studio UI → Sign-in screen: opens (evidence: `frontend/src/App.tsx`)
- Insights Studio UI → API client: calls (evidence: `frontend/src/App.tsx`)
- Sign-in screen → API client: submits credentials (evidence: `frontend/src/pages/AuthPage.tsx`)
- Categorization workflow → API client: requests operations
- Dashboard review → API client: requests results (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Study Awareness UI → API client: requests analysis (evidence: `frontend/src/pages/AwarenessIntegrated.tsx`)
- API client → FastAPI application: sends HTTP requests (evidence: `frontend/src/api.ts`)
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Study routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Classification routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Study Awareness routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Standalone Awareness routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Admin routes: registers (evidence: `backend/app/main.py`)
- Authentication routes → Account management: uses (evidence: `backend/app/routers/auth.py`)
- Authentication routes → Security policies: checks policy (evidence: `backend/app/routers/auth.py`)
- Study routes → Import and study service: creates studies (evidence: `backend/app/routers/studies.py`)
- Import and study service → PostgreSQL: persists rows (evidence: `backend/app/services.py`)
- Classification routes → Open-answer coding: classifies responses (evidence: `backend/app/routers/classifications.py`)
- Classification routes → PostgreSQL: saves results (evidence: `backend/app/routers/classifications.py`)
- Classification routes → Brand catalog: uses catalog (evidence: `backend/app/routers/classifications.py`)
- Open-answer coding → LLM providers: requests completion (evidence: `backend/core/coding.py`)
- Classification routes → Quality review: provides quality review (evidence: `backend/app/routers/classifications.py`)
- Classification routes → Insights and segments: provides insights (evidence: `backend/app/routers/classifications.py`)
- Classification routes → Excel exports: provides exports (evidence: `backend/app/routers/classifications.py`)
- Standalone Awareness UI → Standalone Awareness routes: uses service
- Standalone Awareness routes → Flexible Awareness engine: runs analysis
- Flexible Awareness engine → Awareness calculations: uses calculations (evidence: `backend/core/awareness_flex.py`)
- Study Awareness routes → Awareness calculations: uses calculations
- Insights Studio UI → Help assistant: offers assistant
- Help assistant → Help knowledge base: uses knowledge
- Admin routes → Security policies: manages policy (evidence: `backend/app/routers/admin.py`)
- LLM providers → Researcher: calls AI providers