# joaofernandesuk/reponary architecture

> Architecture diagram of the GitHub repository joaofernandesuk/reponary, 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/joaofernandesuk/reponary
- Repository: https://github.com/joaofernandesuk/reponary
- Video tour (about a minute): https://gitdiagram.com/joaofernandesuk/reponary/video

## Overview

Reponary is a local-first browser workspace combining code-graph inspection with Markdown engineering knowledge. The main workflow is to validate and register a source folder, optionally generate its Graphify graph on the host, then browse project status, graph data, notes, and search results. The host agent owns privileged host operations; the web application serves read-only project and vault data. Graph generation and deployment details are described in the README, while some operation implementations were not sampled, so those links are limited to documented behavior.

Main entry points: [`backend/app.py`](https://github.com/joaofernandesuk/reponary/blob/main/backend/app.py) (HTTP API), [`host/agent.py`](https://github.com/joaofernandesuk/reponary/blob/main/host/agent.py) (Native agent), [`backend/index.py`](https://github.com/joaofernandesuk/reponary/blob/main/backend/index.py) (Search index), [`backend/knowledge.py`](https://github.com/joaofernandesuk/reponary/blob/main/backend/knowledge.py) (Knowledge index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser interface"]
  node_ui["Workspace UI<br/>[main.tsx]"]
  node_client["HTTP client<br/>[api.ts]"]
end

subgraph group_web["Web application"]
  node_api["HTTP API<br/>[app.py]"]
  node_control["Control bridge<br/>[control.py]"]
  node_knowledge["Knowledge index<br/>[knowledge.py]"]
  node_search["Search index<br/>[index.py]"]
end

subgraph group_host["Host control"]
  node_agent["Native agent<br/>[agent.py]"]
end

subgraph group_data["Project data"]
  node_repo["Source folders"]
  node_graph["Graphify outputs"]
  node_vault["Markdown vault"]
  node_fts[("SQLite FTS5 cache")]
end

node_user(("Local user"))
node_graphify["Graphify CLI"]
node_compose["Docker Compose"]

node_user -->|"uses"| node_ui
node_ui -->|"requests"| node_client
node_client -->|"calls"| node_api
node_api -->|"submits operations"| node_control
node_agent -->|"polls and reports"| node_api
node_api -->|"reads notes"| node_knowledge
node_api -->|"searches"| node_search
node_knowledge -->|"reads and indexes"| node_vault
node_search -->|"refreshes notes"| node_knowledge
node_search -->|"indexes graph data"| node_graph
node_search -->|"writes and queries"| node_fts
node_agent -->|"validates and manages"| node_repo
node_agent -.->|"generates graphs"| node_graphify
node_agent -->|"manages web service"| node_compose
node_api -->|"reads graph status"| node_graph

click node_ui "https://github.com/joaofernandesuk/reponary/blob/main/frontend/src/main.tsx"
click node_client "https://github.com/joaofernandesuk/reponary/blob/main/frontend/src/api.ts"
click node_api "https://github.com/joaofernandesuk/reponary/blob/main/backend/app.py"
click node_control "https://github.com/joaofernandesuk/reponary/blob/main/backend/control.py"
click node_knowledge "https://github.com/joaofernandesuk/reponary/blob/main/backend/knowledge.py"
click node_search "https://github.com/joaofernandesuk/reponary/blob/main/backend/index.py"
click node_agent "https://github.com/joaofernandesuk/reponary/blob/main/host/agent.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_ui,node_client,node_user toneBlue
class node_api,node_control,node_knowledge,node_search toneAmber
class node_agent toneMint
class node_repo,node_graph,node_vault,node_fts toneRose
class node_graphify,node_compose toneIndigo
```

## Components

### Browser interface

- [Workspace UI](https://github.com/joaofernandesuk/reponary/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [HTTP client](https://github.com/joaofernandesuk/reponary/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Web application

- [HTTP API](https://github.com/joaofernandesuk/reponary/blob/main/backend/app.py): `backend/app.py`
- [Control bridge](https://github.com/joaofernandesuk/reponary/blob/main/backend/control.py): `backend/control.py`
- [Knowledge index](https://github.com/joaofernandesuk/reponary/blob/main/backend/knowledge.py): `backend/knowledge.py`
- [Search index](https://github.com/joaofernandesuk/reponary/blob/main/backend/index.py): `backend/index.py`

### Host control

- [Native agent](https://github.com/joaofernandesuk/reponary/blob/main/host/agent.py): `host/agent.py`

### Project data

- **Source folders**
- **Graphify outputs**
- **Markdown vault**
- **SQLite FTS5 cache**

### Other components

- **Local user**
- **Graphify CLI**
- **Docker Compose**

## Connections

- Local user → Workspace UI: uses
- Workspace UI → HTTP client: requests
- HTTP client → HTTP API: calls
- HTTP API → Control bridge: submits operations
- Native agent → HTTP API: polls and reports
- HTTP API → Knowledge index: reads notes
- HTTP API → Search index: searches
- Knowledge index → Markdown vault: reads and indexes
- Search index → Knowledge index: refreshes notes
- Search index → Graphify outputs: indexes graph data
- Search index → SQLite FTS5 cache: writes and queries
- Native agent → Source folders: validates and manages
- Native agent → Graphify CLI: generates graphs
- Native agent → Docker Compose: manages web service
- HTTP API → Graphify outputs: reads graph status