# aelena/flowtrack architecture

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

- Interactive diagram: https://gitdiagram.com/aelena/flowtrack
- Repository: https://github.com/aelena/flowtrack

## Overview

FlowTrack is a project-triage tracker: users organize projects into areas, record tasks and notes, and compare task-derived completion with their own estimate against explicit abandonment criteria. The Svelte UI calls a FastAPI API backed by PostgreSQL; an MCP server lets agents inspect and update the same portfolio through REST. The graph includes documented file, configuration, backup, document-generation, and browser-clipper capabilities. Some feature implementations were not sampled, so their internal connections are omitted rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/aelena/flowtrack/blob/main/backend/app/main.py) (HTTP API), [`backend/app/database.py`](https://github.com/aelena/flowtrack/blob/main/backend/app/database.py) (Database sessions), [`frontend/src/lib/api.js`](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/api.js) (Web API client), [`frontend/src/lib/components/ProjectView.svelte`](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/ProjectView.svelte) (Project workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_webapp["Home and settings<br/>[+page.svelte]"]
  node_projectview["Project workspace<br/>[ProjectView.svelte]"]
  node_sidebar["Project navigation<br/>[Sidebar.svelte]"]
  node_commands["Commands and exports<br/>[CommandBar.svelte]"]
  node_tasksui["Task editor<br/>[TaskList.svelte]"]
  node_notesui["Notes and writing<br/>[NoteEditor.svelte]"]
  node_writemode["Write mode<br/>[WriteMode.svelte]"]
  node_apiclient["Web API client<br/>[api.js]"]
end

subgraph group_api["API and domain"]
  node_apiapp["HTTP API<br/>[main.py]"]
  node_projectapi["Project lifecycle<br/>[projects.py]"]
  node_areaapi["Areas<br/>[areas.py]"]
  node_taskapi["Task operations<br/>[tasks.py]"]
  node_noteapi["Notes<br/>[notes.py]"]
  node_fileapi["Project files<br/>[files.py]"]
  node_backupapi["Backup and restore<br/>[backup.py]"]
  node_configapi["Configuration<br/>[config.py]"]
  node_documentsapi["Project documents<br/>[documents.py]"]
  node_extensionapi["Browser clipper<br/>[extension.py]"]
end

subgraph group_data["Persistence"]
  node_models["Domain records<br/>[models.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_agent["Agent and integrations"]
  node_mcpserver["MCP tools and prompts<br/>[server.py]"]
  node_mcpclient["REST transport<br/>[client.py]"]
end

node_user(("User"))
node_agentactor(("Agent"))

node_user -->|"uses"| node_webapp
node_webapp -->|"shows navigation"| node_sidebar
node_webapp -->|"loads portfolio"| node_apiclient
node_user -->|"opens project"| node_projectview
node_projectview -->|"requests project data"| node_apiclient
node_projectview -->|"renders tasks"| node_tasksui
node_projectview -->|"renders notes"| node_notesui
node_projectview -->|"renders commands"| node_commands
node_projectview -->|"renders writing"| node_writemode
node_sidebar -->|"requests projects"| node_apiclient
node_tasksui -->|"updates tasks"| node_apiclient
node_notesui -->|"updates notes"| node_apiclient
node_commands -->|"requests exports"| node_apiclient
node_writemode -->|"supports writing"| node_notesui
node_apiclient -->|"sends API requests"| node_apiapp
node_apiapp -->|"registers routes"| node_projectapi
node_apiapp -->|"registers routes"| node_areaapi
node_apiapp -->|"registers routes"| node_taskapi
node_apiapp -->|"registers routes"| node_noteapi
node_apiapp -->|"registers routes"| node_fileapi
node_apiapp -->|"registers routes"| node_backupapi
node_apiapp -->|"registers routes"| node_configapi
node_apiapp -->|"registers routes"| node_documentsapi
node_apiapp -->|"registers routes"| node_extensionapi
node_projectapi -->|"uses sessions"| node_database
node_areaapi -->|"uses sessions"| node_database
node_taskapi -->|"uses sessions"| node_database
node_noteapi -->|"uses sessions"| node_database
node_fileapi -->|"uses sessions"| node_database
node_backupapi -->|"uses sessions"| node_database
node_configapi -->|"uses settings"| node_database
node_documentsapi -->|"reads records"| node_database
node_extensionapi -->|"uses sessions"| node_database
node_database -->|"persists data"| node_postgres
node_projectapi -->|"queries projects"| node_models
node_taskapi -->|"creates tasks"| node_models
node_noteapi -->|"manages notes"| node_models
node_fileapi -->|"manages file records"| node_models
node_agentactor -->|"invokes tools"| node_mcpserver
node_mcpserver -->|"calls transport"| node_mcpclient
node_mcpclient -->|"calls REST API"| node_apiapp

click node_webapp "https://github.com/aelena/flowtrack/blob/main/frontend/src/routes/%2Bpage.svelte"
click node_projectview "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/ProjectView.svelte"
click node_sidebar "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/Sidebar.svelte"
click node_commands "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/CommandBar.svelte"
click node_tasksui "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/TaskList.svelte"
click node_notesui "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/NoteEditor.svelte"
click node_writemode "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/WriteMode.svelte"
click node_apiclient "https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/api.js"
click node_apiapp "https://github.com/aelena/flowtrack/blob/main/backend/app/main.py"
click node_projectapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/projects.py"
click node_areaapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/areas.py"
click node_taskapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/tasks.py"
click node_noteapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/notes.py"
click node_fileapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/files.py"
click node_backupapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/backup.py"
click node_configapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/config.py"
click node_documentsapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/documents.py"
click node_extensionapi "https://github.com/aelena/flowtrack/blob/main/backend/app/routers/extension.py"
click node_models "https://github.com/aelena/flowtrack/blob/main/backend/app/models.py"
click node_database "https://github.com/aelena/flowtrack/blob/main/backend/app/database.py"
click node_mcpserver "https://github.com/aelena/flowtrack/blob/main/mcp-server/src/flowtrack_mcp/server.py"
click node_mcpclient "https://github.com/aelena/flowtrack/blob/main/mcp-server/src/flowtrack_mcp/client.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_projectview,node_sidebar,node_commands,node_tasksui,node_notesui,node_writemode,node_apiclient,node_user toneBlue
class node_apiapp,node_projectapi,node_areaapi,node_taskapi,node_noteapi,node_fileapi,node_backupapi,node_configapi,node_documentsapi,node_extensionapi toneAmber
class node_models,node_database,node_postgres toneMint
class node_mcpserver,node_mcpclient toneRose
class node_agentactor toneIndigo
```

## Components

### Web interface

- [Home and settings](https://github.com/aelena/flowtrack/blob/main/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Project workspace](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/ProjectView.svelte): `frontend/src/lib/components/ProjectView.svelte`
- [Project navigation](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/Sidebar.svelte): `frontend/src/lib/components/Sidebar.svelte`
- [Commands and exports](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/CommandBar.svelte): `frontend/src/lib/components/CommandBar.svelte`
- [Task editor](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/TaskList.svelte): `frontend/src/lib/components/TaskList.svelte`
- [Notes and writing](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/NoteEditor.svelte): `frontend/src/lib/components/NoteEditor.svelte`
- [Write mode](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/components/WriteMode.svelte): `frontend/src/lib/components/WriteMode.svelte`
- [Web API client](https://github.com/aelena/flowtrack/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### API and domain

- [HTTP API](https://github.com/aelena/flowtrack/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project lifecycle](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/projects.py): `backend/app/routers/projects.py`
- [Areas](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/areas.py): `backend/app/routers/areas.py`
- [Task operations](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/tasks.py): `backend/app/routers/tasks.py`
- [Notes](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/notes.py): `backend/app/routers/notes.py`
- [Project files](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/files.py): `backend/app/routers/files.py`
- [Backup and restore](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/backup.py): `backend/app/routers/backup.py`
- [Configuration](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/config.py): `backend/app/routers/config.py`
- [Project documents](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/documents.py): `backend/app/routers/documents.py`
- [Browser clipper](https://github.com/aelena/flowtrack/blob/main/backend/app/routers/extension.py): `backend/app/routers/extension.py`

### Persistence

- [Domain records](https://github.com/aelena/flowtrack/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database sessions](https://github.com/aelena/flowtrack/blob/main/backend/app/database.py): `backend/app/database.py`
- **PostgreSQL**

### Agent and integrations

- [MCP tools and prompts](https://github.com/aelena/flowtrack/blob/main/mcp-server/src/flowtrack_mcp/server.py): `mcp-server/src/flowtrack_mcp/server.py`
- [REST transport](https://github.com/aelena/flowtrack/blob/main/mcp-server/src/flowtrack_mcp/client.py): `mcp-server/src/flowtrack_mcp/client.py`

### Other components

- **User**
- **Agent**

## Connections

- User → Home and settings: uses (evidence: `README.md`)
- Home and settings → Project navigation: shows navigation (evidence: `frontend/src/routes/+page.svelte`)
- Home and settings → Web API client: loads portfolio (evidence: `frontend/src/routes/+page.svelte`)
- User → Project workspace: opens project (evidence: `README.md`)
- Project workspace → Web API client: requests project data (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Project workspace → Task editor: renders tasks (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Project workspace → Notes and writing: renders notes (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Project workspace → Commands and exports: renders commands (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Project workspace → Write mode: renders writing (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Project navigation → Web API client: requests projects (evidence: `frontend/src/lib/components/Sidebar.svelte`)
- Task editor → Web API client: updates tasks (evidence: `frontend/src/lib/components/TaskList.svelte`)
- Notes and writing → Web API client: updates notes (evidence: `frontend/src/lib/components/NoteEditor.svelte`)
- Commands and exports → Web API client: requests exports (evidence: `frontend/src/lib/components/CommandBar.svelte`)
- Write mode → Notes and writing: supports writing (evidence: `frontend/src/lib/components/ProjectView.svelte`)
- Web API client → HTTP API: sends API requests (evidence: `frontend/src/lib/api.js`)
- HTTP API → Project lifecycle: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Areas: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Task operations: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Notes: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Project files: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Backup and restore: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Configuration: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Project documents: registers routes (evidence: `backend/app/main.py`)
- HTTP API → Browser clipper: registers routes (evidence: `backend/app/main.py`)
- Project lifecycle → Database sessions: uses sessions (evidence: `backend/app/routers/projects.py`)
- Areas → Database sessions: uses sessions (evidence: `backend/app/routers/areas.py`)
- Task operations → Database sessions: uses sessions (evidence: `backend/app/routers/tasks.py`)
- Notes → Database sessions: uses sessions (evidence: `backend/app/routers/notes.py`)
- Project files → Database sessions: uses sessions (evidence: `backend/app/routers/files.py`)
- Backup and restore → Database sessions: uses sessions (evidence: `backend/app/routers/backup.py`)
- Configuration → Database sessions: uses settings (evidence: `backend/app/routers/config.py`)
- Project documents → Database sessions: reads records (evidence: `backend/app/routers/documents.py`)
- Browser clipper → Database sessions: uses sessions (evidence: `backend/app/routers/extension.py`)
- Database sessions → PostgreSQL: persists data (evidence: `README.md`)
- Project lifecycle → Domain records: queries projects (evidence: `backend/app/routers/projects.py`)
- Task operations → Domain records: creates tasks (evidence: `backend/app/routers/tasks.py`)
- Notes → Domain records: manages notes (evidence: `backend/app/routers/notes.py`)
- Project files → Domain records: manages file records (evidence: `backend/app/routers/files.py`)
- Agent → MCP tools and prompts: invokes tools (evidence: `README.md`)
- MCP tools and prompts → REST transport: calls transport (evidence: `mcp-server/src/flowtrack_mcp/server.py`)
- REST transport → HTTP API: calls REST API (evidence: `README.md`)
