# tayadj/semantic-file-system architecture

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

- Interactive diagram: https://gitdiagram.com/tayadj/semantic-file-system
- Repository: https://github.com/tayadj/semantic-file-system

## Overview

Semantic-File-System is a local multimodal file index with semantic search and a chat interface. Users browse or add indexed files, search by meaning, and work with chat sessions; the backend stores index, context, and knowledge state and uses a model-runner service for embeddings and generated descriptions or replies. The frontend also exposes file-type-specific views and knowledge skills. The README is only a title, so these capabilities and connections are based on the sampled runtime code; unsampled wiring is omitted.

Main entry points: [`src/main.py`](https://github.com/tayadj/semantic-file-system/blob/main/src/main.py) (FastAPI application), [`src/core/engine.py`](https://github.com/tayadj/semantic-file-system/blob/main/src/core/engine.py) (Search and chat engine), [`src/interface/scripts/index/pane.js`](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/pane.js) (Index browser and search), [`src/interface/index.js`](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/index.js) (Browser app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["HTTP application"]
  node_server["FastAPI application<br/>[main.py]"]
  node_engine["Search and chat engine<br/>[engine.py]"]
end

subgraph group_indexing["File indexing"]
  node_index_api["Index API and service<br/>[index.py]"]
end

subgraph group_assistant["Chat and knowledge"]
  node_context_api["Context API and service<br/>[context.py]"]
  node_knowledge_api["Knowledge API and service<br/>[knowledge.py]"]
end

subgraph group_frontend["Browser interface"]
  node_browser["Browser app<br/>[index.js]"]
  node_index_pane["Index browser and search<br/>[pane.js]"]
  node_directory_view["Directory view<br/>[directory.js]"]
  node_text_view["Text view<br/>[textual.js]"]
  node_visual_view["Image view<br/>[visual.js]"]
  node_audio_view["Audio view<br/>[audial.js]"]
  node_context_pane["Chat sessions<br/>[pane.js]"]
  node_chat_view["Chat view<br/>[chat.js]"]
  node_chips["Skill and file mentions<br/>[chip.js]"]
end

subgraph group_runtime["Persistence and models"]
  node_index_state[("Index JSON state<br/>[index.py]")]
  node_context_state[("Context JSON state<br/>[context.py]")]
  node_knowledge_state[("Knowledge JSON state<br/>[knowledge.py]")]
  node_model_runner["Model runner"]
end

node_user(("User"))

node_user -->|"uses"| node_browser
node_browser -->|"HTTP and WebSocket"| node_server
node_browser -->|"creates"| node_index_pane
node_browser -->|"creates"| node_context_pane
node_index_pane -->|"uploads and searches"| node_server
node_index_pane -->|"renders"| node_directory_view
node_index_pane -->|"renders"| node_text_view
node_index_pane -->|"renders"| node_visual_view
node_index_pane -->|"renders"| node_audio_view
node_context_pane -->|"session requests"| node_server
node_context_pane -->|"renders"| node_chat_view
node_context_pane -->|"uses mentions"| node_chips
node_server -->|"dispatches search and chat"| node_engine
node_server -->|"mounts routes"| node_index_api
node_server -->|"mounts routes"| node_context_api
node_server -->|"mounts routes"| node_knowledge_api
node_engine -->|"reads and updates"| node_index_api
node_engine -->|"reads and updates"| node_context_api
node_engine -->|"requests model output"| node_model_runner
node_index_api -->|"reads and writes"| node_index_state
node_context_api -->|"reads and writes"| node_context_state
node_knowledge_api -->|"reads and writes"| node_knowledge_state
node_engine -->|"uses service"| node_knowledge_api
node_engine -->|"requests embeddings and descriptions"| node_model_runner

click node_server "https://github.com/tayadj/semantic-file-system/blob/main/src/main.py"
click node_engine "https://github.com/tayadj/semantic-file-system/blob/main/src/core/engine.py"
click node_index_api "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/index.py"
click node_index_state "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/index.py"
click node_context_api "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/context.py"
click node_context_state "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/context.py"
click node_knowledge_api "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/knowledge.py"
click node_knowledge_state "https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/knowledge.py"
click node_browser "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/index.js"
click node_index_pane "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/pane.js"
click node_directory_view "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/directory.js"
click node_text_view "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/textual.js"
click node_visual_view "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/visual.js"
click node_audio_view "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/audial.js"
click node_context_pane "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/context/pane.js"
click node_chat_view "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/context/views/chat.js"
click node_chips "https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/chip.js"

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_server,node_engine,node_user toneBlue
class node_index_api toneAmber
class node_context_api,node_knowledge_api toneMint
class node_browser,node_index_pane,node_directory_view,node_text_view,node_visual_view,node_audio_view,node_context_pane,node_chat_view,node_chips toneRose
class node_index_state,node_context_state,node_knowledge_state,node_model_runner toneIndigo
```

## Components

### HTTP application

- [FastAPI application](https://github.com/tayadj/semantic-file-system/blob/main/src/main.py): `src/main.py`
- [Search and chat engine](https://github.com/tayadj/semantic-file-system/blob/main/src/core/engine.py): `src/core/engine.py`

### File indexing

- [Index API and service](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/index.py): `src/core/api/index.py`

### Chat and knowledge

- [Context API and service](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/context.py): `src/core/api/context.py`
- [Knowledge API and service](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/knowledge.py): `src/core/api/knowledge.py`

### Browser interface

- [Browser app](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/index.js): `src/interface/index.js`
- [Index browser and search](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/pane.js): `src/interface/scripts/index/pane.js`
- [Directory view](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/directory.js): `src/interface/scripts/index/views/directory.js`
- [Text view](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/textual.js): `src/interface/scripts/index/views/textual.js`
- [Image view](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/visual.js): `src/interface/scripts/index/views/visual.js`
- [Audio view](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/index/views/audial.js): `src/interface/scripts/index/views/audial.js`
- [Chat sessions](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/context/pane.js): `src/interface/scripts/context/pane.js`
- [Chat view](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/context/views/chat.js): `src/interface/scripts/context/views/chat.js`
- [Skill and file mentions](https://github.com/tayadj/semantic-file-system/blob/main/src/interface/scripts/chip.js): `src/interface/scripts/chip.js`

### Persistence and models

- [Index JSON state](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/index.py): `src/core/api/index.py`
- [Context JSON state](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/context.py): `src/core/api/context.py`
- [Knowledge JSON state](https://github.com/tayadj/semantic-file-system/blob/main/src/core/api/knowledge.py): `src/core/api/knowledge.py`
- **Model runner**

### Other components

- **User**

## Connections

- User → Browser app: uses
- Browser app → FastAPI application: HTTP and WebSocket
- Browser app → Index browser and search: creates
- Browser app → Chat sessions: creates
- Index browser and search → FastAPI application: uploads and searches
- Index browser and search → Directory view: renders
- Index browser and search → Text view: renders
- Index browser and search → Image view: renders
- Index browser and search → Audio view: renders
- Chat sessions → FastAPI application: session requests
- Chat sessions → Chat view: renders
- Chat sessions → Skill and file mentions: uses mentions
- FastAPI application → Search and chat engine: dispatches search and chat
- FastAPI application → Index API and service: mounts routes
- FastAPI application → Context API and service: mounts routes
- FastAPI application → Knowledge API and service: mounts routes
- Search and chat engine → Index API and service: reads and updates
- Search and chat engine → Context API and service: reads and updates
- Search and chat engine → Model runner: requests model output
- Index API and service → Index JSON state: reads and writes
- Context API and service → Context JSON state: reads and writes
- Knowledge API and service → Knowledge JSON state: reads and writes
- Search and chat engine → Knowledge API and service: uses service
- Search and chat engine → Model runner: requests embeddings and descriptions