# wenkais196-gabriel/greenbean-study-assistant-personal architecture

> Architecture diagram of the GitHub repository wenkais196-gabriel/greenbean-study-assistant-personal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wenkais196-gabriel/greenbean-study-assistant-personal
- Repository: https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal

## Overview

GreenBean is a local-first study assistant that turns course files into page-addressable material for question answering. The main workflow is upload, asynchronous parsing and indexing, then chat retrieval and a cited answer; the workspace can display source units and restore chat history. Separate product branches cover analysis, sections, export, provider settings, traces, and MCP tools. The README documents these capabilities; sampled source confirms upload/job handling and provider configuration, while unsampled subsystem wiring is shown only where the README supports it.

Main entry points: [`backend-python/app/main.py`](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/main.py) (FastAPI app), [`src/lib/apiClient.ts`](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/lib/apiClient.ts) (API client), [`src/features/workspace/pages/WorkspacePage.tsx`](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/pages/WorkspacePage.tsx) (Workspace UI), [`backend-python/app/services/document_ingest_service.py`](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/document_ingest_service.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Study workspace"]
  node_workspace["Workspace UI<br/>[WorkspacePage.tsx]"]
  node_filemanager["File manager<br/>[FileManager.tsx]"]
  node_chatui["Chat interface<br/>[ChatPanel.tsx]"]
  node_documentui["Document viewer<br/>[DocumentViewer.tsx]"]
  node_providerui["Provider settings<br/>[ProviderPanel.tsx]"]
  node_frontendclient["API client<br/>[apiClient.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_documentsapi["Document endpoints"]
  node_chatapi["Chat endpoint<br/>[chat_controller.py]"]
  node_providerapi["Provider endpoints"]
  node_analysisapi["Analysis endpoints"]
  node_exportapi["Export endpoints"]
  node_queryservice["Document queries"]
end

subgraph group_ingestion["Document pipeline"]
  node_ingestjobs["Upload jobs"]
  node_ingest["Document ingestion"]
  node_parsers["Format parsers<br/>[parser_factory.py]"]
  node_chunking["Chunking and embeddings<br/>[chunk_service.py]"]
end

subgraph group_intelligence["AI capabilities"]
  node_chatservice["Chat orchestration<br/>[chat_service.py]"]
  node_agents["Agent tools<br/>[chat_agent.py]"]
  node_retrieval["RAG retrieval<br/>[retriever.py]"]
  node_providers["Model providers<br/>[registry.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_analysis["Analysis service"]
  node_export["Export service<br/>[export_service.py]"]
end

subgraph group_state["Persistence"]
  node_database[("SQLite data store<br/>[models.py]")]
end

node_student(("Student"))
node_externalmodel(("Configured LLM"))

node_student -->|"uses"| node_workspace
node_workspace -->|"presents"| node_filemanager
node_workspace -->|"presents"| node_chatui
node_workspace -->|"presents"| node_documentui
node_filemanager -->|"uploads and polls"| node_frontendclient
node_chatui -->|"sends questions"| node_frontendclient
node_documentui -->|"loads source units"| node_frontendclient
node_providerui -->|"manages providers"| node_frontendclient
node_frontendclient -->|"calls API"| node_backend
node_backend -->|"registers routes"| node_documentsapi
node_backend -->|"registers routes"| node_chatapi
node_backend -->|"registers routes"| node_providerapi
node_documentsapi -->|"submits and queries"| node_ingestjobs
node_ingestjobs -->|"runs ingestion"| node_ingest
node_ingest -->|"parses files"| node_parsers
node_ingest -->|"chunks and embeds"| node_chunking
node_ingest -->|"persists records and vectors"| node_database
node_documentsapi -->|"queries documents"| node_queryservice
node_queryservice -->|"reads documents"| node_database
node_chatapi -->|"handles chat"| node_chatservice
node_chatservice -->|"orchestrates tools"| node_agents
node_agents -->|"retrieves context"| node_retrieval
node_retrieval -->|"searches indexed content"| node_database
node_chatservice -->|"gets active model"| node_providers
node_providers -->|"requests completions"| node_externalmodel
node_providerapi -->|"configures and activates"| node_providers
node_chatservice -->|"persists sessions and messages"| node_database
node_backend -->|"registers routes"| node_analysisapi
node_analysisapi -->|"dispatches analysis"| node_analysis
node_backend -->|"registers routes"| node_exportapi
node_exportapi -->|"dispatches export"| node_export
node_mcp -.->|"exposes tools"| node_agents

click node_workspace "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/pages/WorkspacePage.tsx"
click node_filemanager "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/left/FileManager.tsx"
click node_chatui "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/right/ChatPanel.tsx"
click node_documentui "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/center/DocumentViewer.tsx"
click node_providerui "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/provider/components/ProviderPanel.tsx"
click node_frontendclient "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/lib/apiClient.ts"
click node_backend "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/main.py"
click node_documentsapi "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/document_controller.py"
click node_chatapi "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/chat_controller.py"
click node_providerapi "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/provider_controller.py"
click node_analysisapi "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/analysis_controller.py"
click node_exportapi "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/export_controller.py"
click node_ingestjobs "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/ingest_job_service.py"
click node_ingest "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/document_ingest_service.py"
click node_parsers "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/parsers/parser_factory.py"
click node_chunking "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/chunk_service.py"
click node_chatservice "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/chat_service.py"
click node_agents "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/agents/chat_agent.py"
click node_retrieval "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/rag/retriever.py"
click node_providers "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/providers/registry.py"
click node_mcp "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/mcp_server.py"
click node_database "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/db/models.py"
click node_queryservice "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/document_query_service.py"
click node_analysis "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/analysis_service.py"
click node_export "https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/export_service.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_workspace,node_filemanager,node_chatui,node_documentui,node_providerui,node_frontendclient toneBlue
class node_backend,node_documentsapi,node_chatapi,node_providerapi,node_analysisapi,node_exportapi,node_queryservice toneAmber
class node_ingestjobs,node_ingest,node_parsers,node_chunking toneMint
class node_chatservice,node_agents,node_retrieval,node_providers,node_mcp,node_analysis,node_export toneRose
class node_database,node_student,node_externalmodel toneIndigo
```

## Components

### Study workspace

- [Workspace UI](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/pages/WorkspacePage.tsx): `src/features/workspace/pages/WorkspacePage.tsx`
- [File manager](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/left/FileManager.tsx): `src/features/workspace/components/left/FileManager.tsx`
- [Chat interface](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/right/ChatPanel.tsx): `src/features/workspace/components/right/ChatPanel.tsx`
- [Document viewer](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/workspace/components/center/DocumentViewer.tsx): `src/features/workspace/components/center/DocumentViewer.tsx`
- [Provider settings](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/features/provider/components/ProviderPanel.tsx): `src/features/provider/components/ProviderPanel.tsx`
- [API client](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/src/lib/apiClient.ts): `src/lib/apiClient.ts`

### Backend API

- [FastAPI app](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/main.py): `backend-python/app/main.py`
- [Document endpoints](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/document_controller.py): `backend-python/app/api/document_controller.py`
- [Chat endpoint](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/chat_controller.py): `backend-python/app/api/chat_controller.py`
- [Provider endpoints](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/provider_controller.py): `backend-python/app/api/provider_controller.py`
- [Analysis endpoints](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/analysis_controller.py): `backend-python/app/api/analysis_controller.py`
- [Export endpoints](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/api/export_controller.py): `backend-python/app/api/export_controller.py`
- [Document queries](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/document_query_service.py): `backend-python/app/services/document_query_service.py`

### Document pipeline

- [Upload jobs](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/ingest_job_service.py): `backend-python/app/services/ingest_job_service.py`
- [Document ingestion](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/document_ingest_service.py): `backend-python/app/services/document_ingest_service.py`
- [Format parsers](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/parsers/parser_factory.py): `backend-python/app/parsers/parser_factory.py`
- [Chunking and embeddings](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/chunk_service.py): `backend-python/app/services/chunk_service.py`

### AI capabilities

- [Chat orchestration](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/chat_service.py): `backend-python/app/services/chat_service.py`
- [Agent tools](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/agents/chat_agent.py): `backend-python/app/agents/chat_agent.py`
- [RAG retrieval](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/rag/retriever.py): `backend-python/app/rag/retriever.py`
- [Model providers](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/providers/registry.py): `backend-python/app/providers/registry.py`
- [MCP server](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/mcp_server.py): `backend-python/app/mcp_server.py`
- [Analysis service](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/analysis_service.py): `backend-python/app/services/analysis_service.py`
- [Export service](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/services/export_service.py): `backend-python/app/services/export_service.py`

### Persistence

- [SQLite data store](https://github.com/wenkais196-gabriel/greenbean-study-assistant-personal/blob/main/backend-python/app/db/models.py): `backend-python/app/db/models.py`

### Other components

- **Student**
- **Configured LLM**

## Connections

- Student → Workspace UI: uses
- Workspace UI → File manager: presents
- Workspace UI → Chat interface: presents
- Workspace UI → Document viewer: presents
- File manager → API client: uploads and polls
- Chat interface → API client: sends questions
- Document viewer → API client: loads source units
- Provider settings → API client: manages providers
- API client → FastAPI app: calls API
- FastAPI app → Document endpoints: registers routes
- FastAPI app → Chat endpoint: registers routes
- FastAPI app → Provider endpoints: registers routes
- Document endpoints → Upload jobs: submits and queries
- Upload jobs → Document ingestion: runs ingestion
- Document ingestion → Format parsers: parses files
- Document ingestion → Chunking and embeddings: chunks and embeds
- Document ingestion → SQLite data store: persists records and vectors
- Document endpoints → Document queries: queries documents
- Document queries → SQLite data store: reads documents
- Chat endpoint → Chat orchestration: handles chat
- Chat orchestration → Agent tools: orchestrates tools
- Agent tools → RAG retrieval: retrieves context
- RAG retrieval → SQLite data store: searches indexed content
- Chat orchestration → Model providers: gets active model
- Model providers → Configured LLM: requests completions
- Provider endpoints → Model providers: configures and activates
- Chat orchestration → SQLite data store: persists sessions and messages
- FastAPI app → Analysis endpoints: registers routes
- Analysis endpoints → Analysis service: dispatches analysis
- FastAPI app → Export endpoints: registers routes
- Export endpoints → Export service: dispatches export
- MCP server → Agent tools: exposes tools