# glindsays/bizsop-workspace architecture

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

- Interactive diagram: https://gitdiagram.com/glindsays/bizsop-workspace
- Repository: https://github.com/glindsays/bizsop-workspace

## Overview

BizSOP Flow is an internal SOP knowledge and workflow assistant. Users upload PDFs for indexing, ask document-grounded questions with citations and conversation history, and generate SOP flowcharts with role-based checklists. The backend exposes these capabilities through FastAPI routers and uses Supabase for document/conversation data and Gemini for embeddings and generated responses. Frontend components and pages are included as product surfaces, but their wiring to the API is not established by the available relationship evidence; the README is empty.

Main entry points: [`backend/app/core/database.py`](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/core/database.py) (Supabase and Gemini clients), [`backend/app/main.py`](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/upload.py`](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/upload.py) (PDF upload and lifecycle), [`backend/app/services/rag_engine.py`](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/rag_engine.py) (Retrieval and answering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interface"]
  node_home["Document workspace<br/>[page.tsx]"]
  node_chatui["Chat interface<br/>[ChatInterface.tsx]"]
  node_convui["Conversation list"]
  node_uploadui["PDF uploader<br/>[PdfUploader.tsx]"]
  node_picker["Document picker<br/>[DocumentPicker.tsx]"]
  node_flowui["Flowchart view<br/>[page.tsx]"]
  node_mermaid["Diagram visualizer"]
  node_checklist["Task checklist<br/>[TaskChecklist.tsx]"]
end

subgraph group_api["API Workflows"]
  node_app["FastAPI application<br/>[main.py]"]
  node_upload["PDF upload and lifecycle<br/>[upload.py]"]
  node_chat["Chat and citations<br/>[chat.py]"]
  node_conversations["Conversation management<br/>[conversations.py]"]
  node_flowroute["Flowchart endpoint<br/>[flowchart.py]"]
end

subgraph group_knowledge["Document Intelligence"]
  node_parser["PDF parsing and chunking<br/>[pdf_parser.py]"]
  node_embedding["Chunk embedding<br/>[embedding.py]"]
  node_rag["Retrieval and answering<br/>[rag_engine.py]"]
  node_generator["Diagram generation<br/>[generator.py]"]
end

subgraph group_state["Persistence and Models"]
  node_database["Supabase and Gemini clients<br/>[database.py]"]
end

node_user(("SOP user"))
node_supabase[("Supabase")]
node_gemini["Gemini API"]

node_user -.->|"uses"| node_home
node_app -->|"registers route"| node_upload
node_app -->|"registers route"| node_chat
node_app -->|"registers route"| node_flowroute
node_app -->|"registers route"| node_conversations
node_upload -->|"parses PDF"| node_parser
node_upload -->|"queues indexing"| node_embedding
node_upload -->|"stores metadata"| node_database
node_embedding -->|"stores vectors"| node_database
node_embedding -->|"creates embeddings"| node_gemini
node_chat -->|"retrieves and answers"| node_rag
node_chat -->|"loads chat state"| node_database
node_conversations -->|"manages records"| node_database
node_flowroute -->|"loads SOP chunks"| node_database
node_flowroute -->|"requests diagram"| node_generator
node_generator -->|"uses model fallback"| node_rag
node_database -->|"connects"| node_supabase
node_rag -->|"retrieves chunks"| node_database
node_rag -->|"generates response"| node_gemini

click node_home "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/app/page.tsx"
click node_chatui "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/ChatInterface.tsx"
click node_convui "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/ConversationList.tsx"
click node_uploadui "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/PdfUploader.tsx"
click node_picker "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/DocumentPicker.tsx"
click node_flowui "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/app/flowchart/page.tsx"
click node_mermaid "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/MermaidVisualizer.tsx"
click node_checklist "https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/TaskChecklist.tsx"
click node_app "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/main.py"
click node_upload "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/upload.py"
click node_chat "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/chat.py"
click node_conversations "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/conversations.py"
click node_flowroute "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/flowchart.py"
click node_parser "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/pdf_parser.py"
click node_embedding "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/embedding.py"
click node_rag "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/rag_engine.py"
click node_generator "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/generator.py"
click node_database "https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/core/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_home,node_chatui,node_convui,node_uploadui,node_picker,node_flowui,node_mermaid,node_checklist,node_user toneBlue
class node_app,node_upload,node_chat,node_conversations,node_flowroute,node_supabase toneAmber
class node_parser,node_embedding,node_rag,node_generator,node_gemini toneMint
class node_database toneRose
```

## Components

### User Interface

- [Document workspace](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Chat interface](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/ChatInterface.tsx): `frontend/src/components/ChatInterface.tsx`
- [Conversation list](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/ConversationList.tsx): `frontend/src/components/ConversationList.tsx`
- [PDF uploader](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/PdfUploader.tsx): `frontend/src/components/PdfUploader.tsx`
- [Document picker](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/DocumentPicker.tsx): `frontend/src/components/DocumentPicker.tsx`
- [Flowchart view](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/app/flowchart/page.tsx): `frontend/src/app/flowchart/page.tsx`
- [Diagram visualizer](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/MermaidVisualizer.tsx): `frontend/src/components/MermaidVisualizer.tsx`
- [Task checklist](https://github.com/glindsays/bizsop-workspace/blob/main/frontend/src/components/TaskChecklist.tsx): `frontend/src/components/TaskChecklist.tsx`

### API Workflows

- [FastAPI application](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/main.py): `backend/app/main.py`
- [PDF upload and lifecycle](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/upload.py): `backend/app/routers/upload.py`
- [Chat and citations](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Conversation management](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/conversations.py): `backend/app/routers/conversations.py`
- [Flowchart endpoint](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/routers/flowchart.py): `backend/app/routers/flowchart.py`

### Document Intelligence

- [PDF parsing and chunking](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/pdf_parser.py): `backend/app/services/pdf_parser.py`
- [Chunk embedding](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/embedding.py): `backend/app/services/embedding.py`
- [Retrieval and answering](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/rag_engine.py): `backend/app/services/rag_engine.py`
- [Diagram generation](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/services/generator.py): `backend/app/services/generator.py`

### Persistence and Models

- [Supabase and Gemini clients](https://github.com/glindsays/bizsop-workspace/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **SOP user**
- **Supabase**
- **Gemini API**

## Connections

- SOP user → Document workspace: uses
- FastAPI application → PDF upload and lifecycle: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Chat and citations: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Flowchart endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Conversation management: registers route (evidence: `backend/app/main.py`)
- PDF upload and lifecycle → PDF parsing and chunking: parses PDF (evidence: `backend/app/routers/upload.py`)
- PDF upload and lifecycle → Chunk embedding: queues indexing (evidence: `backend/app/routers/upload.py`)
- PDF upload and lifecycle → Supabase and Gemini clients: stores metadata (evidence: `backend/app/routers/upload.py`)
- Chunk embedding → Supabase and Gemini clients: stores vectors (evidence: `backend/app/services/embedding.py`)
- Chunk embedding → Gemini API: creates embeddings (evidence: `backend/app/services/embedding.py`)
- Chat and citations → Retrieval and answering: retrieves and answers (evidence: `backend/app/routers/chat.py`)
- Chat and citations → Supabase and Gemini clients: loads chat state (evidence: `backend/app/routers/chat.py`)
- Conversation management → Supabase and Gemini clients: manages records (evidence: `backend/app/routers/conversations.py`)
- Flowchart endpoint → Supabase and Gemini clients: loads SOP chunks (evidence: `backend/app/routers/flowchart.py`)
- Flowchart endpoint → Diagram generation: requests diagram (evidence: `backend/app/routers/flowchart.py`)
- Diagram generation → Retrieval and answering: uses model fallback (evidence: `backend/app/services/generator.py`)
- Supabase and Gemini clients → Supabase: connects (evidence: `backend/app/core/database.py`)
- Retrieval and answering → Supabase and Gemini clients: retrieves chunks (evidence: `backend/app/services/rag_engine.py`)
- Retrieval and answering → Gemini API: generates response (evidence: `backend/app/services/rag_engine.py`)