# t73fde/zettelstore architecture

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

- Interactive diagram: https://gitdiagram.com/t73fde/zettelstore
- Repository: https://github.com/t73fde/zettelstore

## Overview

Zettelstore is a self-hosted knowledge-management system for collecting durable notes (zettel) and linking them. Users enter through the web UI or the broader HTTP API: requests are routed, authenticated, handled by use cases, and served from managed boxes; note content is parsed or evaluated and results encoded for presentation. The README also highlights multiple interfaces and security by default. The graph includes documented runtime layers and key storage, query, parsing, and rendering capabilities. Several subsystems are represented by directory paths because their individual source was not sampled; links are limited to visible calls or README-described roles.

Main entry points: [`internal/box/manager/manager.go`](https://github.com/t73fde/zettelstore/blob/master/internal/box/manager/manager.go) (Box manager), [`cmd/main.go`](https://github.com/t73fde/zettelstore/blob/master/cmd/main.go) (Command entry), [`internal/web/server/router.go`](https://github.com/t73fde/zettelstore/blob/master/internal/web/server/router.go) (HTTP routing), [`internal/usecase`](https://github.com/t73fde/zettelstore/tree/master/internal/usecase) (Zettel operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and access"]
  node_cli["Command entry<br/>[main.go]"]
  node_kernel["Service kernel"]
  node_http["HTTP server"]
  node_router["HTTP routing<br/>[router.go]"]
  node_auth["Authentication"]
end

subgraph group_domain["Note operations"]
  node_usecases["Zettel operations"]
  node_query["Query execution<br/>[query.go]"]
  node_querylang["Query language"]
  node_zettel["Zettel model"]
end

subgraph group_storage["Storage and indexing"]
  node_manager["Box manager<br/>[manager.go]"]
  node_boxapi["Box interface<br/>[box.go]"]
  node_dirbox[("Directory storage<br/>[service.go]")]
  node_filebox[("File and ZIP storage")]
  node_otherboxes["Other box providers"]
end

subgraph group_content["Content processing"]
  node_parser["Syntax parsers<br/>[parser.go]"]
  node_evaluator["Content evaluator"]
end

subgraph group_presentation["Interfaces and output"]
  node_webui["Web interface"]
  node_webapi["HTTP API"]
  node_encoder["Content encoders"]
end

node_operator(("User"))

node_operator -->|"starts"| node_cli
node_cli -->|"configures"| node_kernel
node_cli -->|"creates"| node_manager
node_cli -->|"creates"| node_auth
node_kernel -->|"starts"| node_http
node_operator -->|"sends requests"| node_http
node_http -->|"routes"| node_router
node_router -->|"checks tokens"| node_auth
node_router -.->|"dispatches"| node_webapi
node_router -.->|"dispatches"| node_webui
node_webapi -->|"invokes"| node_usecases
node_webui -.->|"invokes"| node_usecases
node_usecases -.->|"accesses boxes"| node_manager
node_query -.->|"selects metadata"| node_manager
node_query -->|"executes directives"| node_querylang
node_query -->|"evaluates items"| node_evaluator
node_manager -->|"manages"| node_boxapi
node_manager -->|"coordinates"| node_dirbox
node_boxapi -->|"implemented by"| node_dirbox
node_boxapi -.->|"implemented by"| node_otherboxes
node_dirbox -->|"uses"| node_filebox
node_usecases -.->|"parses notes"| node_parser
node_parser -->|"produces parsed notes"| node_zettel
node_evaluator -->|"uses parsed syntax"| node_parser
node_evaluator -->|"retrieves linked notes"| node_boxapi
node_webapi -.->|"formats responses"| node_encoder
node_webui -.->|"renders content"| node_encoder
node_encoder -->|"encodes"| node_zettel

click node_cli "https://github.com/t73fde/zettelstore/blob/master/cmd/main.go"
click node_kernel "https://github.com/t73fde/zettelstore/tree/master/internal/kernel"
click node_http "https://github.com/t73fde/zettelstore/tree/master/internal/web/server"
click node_router "https://github.com/t73fde/zettelstore/blob/master/internal/web/server/router.go"
click node_auth "https://github.com/t73fde/zettelstore/tree/master/internal/auth"
click node_webui "https://github.com/t73fde/zettelstore/tree/master/internal/web/adapter/webui"
click node_webapi "https://github.com/t73fde/zettelstore/tree/master/internal/web/adapter/webapi"
click node_usecases "https://github.com/t73fde/zettelstore/tree/master/internal/usecase"
click node_query "https://github.com/t73fde/zettelstore/blob/master/internal/usecase/query.go"
click node_querylang "https://github.com/t73fde/zettelstore/tree/master/internal/query"
click node_manager "https://github.com/t73fde/zettelstore/blob/master/internal/box/manager/manager.go"
click node_boxapi "https://github.com/t73fde/zettelstore/blob/master/internal/box/box.go"
click node_dirbox "https://github.com/t73fde/zettelstore/blob/master/internal/box/dirbox/service.go"
click node_filebox "https://github.com/t73fde/zettelstore/tree/master/internal/box/filebox"
click node_otherboxes "https://github.com/t73fde/zettelstore/tree/master/internal/box"
click node_parser "https://github.com/t73fde/zettelstore/blob/master/internal/parser/parser.go"
click node_evaluator "https://github.com/t73fde/zettelstore/tree/master/internal/evaluator"
click node_encoder "https://github.com/t73fde/zettelstore/tree/master/internal/encoder"
click node_zettel "https://github.com/t73fde/zettelstore/tree/master/internal/zettel"

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_cli,node_kernel,node_http,node_router,node_auth,node_operator toneBlue
class node_usecases,node_query,node_querylang,node_zettel toneAmber
class node_manager,node_boxapi,node_dirbox,node_filebox,node_otherboxes toneMint
class node_parser,node_evaluator toneRose
class node_webui,node_webapi,node_encoder toneIndigo
```

## Components

### Startup and access

- [Command entry](https://github.com/t73fde/zettelstore/blob/master/cmd/main.go): `cmd/main.go`
- [Service kernel](https://github.com/t73fde/zettelstore/tree/master/internal/kernel): `internal/kernel`
- [HTTP server](https://github.com/t73fde/zettelstore/tree/master/internal/web/server): `internal/web/server`
- [HTTP routing](https://github.com/t73fde/zettelstore/blob/master/internal/web/server/router.go): `internal/web/server/router.go`
- [Authentication](https://github.com/t73fde/zettelstore/tree/master/internal/auth): `internal/auth`

### Note operations

- [Zettel operations](https://github.com/t73fde/zettelstore/tree/master/internal/usecase): `internal/usecase`
- [Query execution](https://github.com/t73fde/zettelstore/blob/master/internal/usecase/query.go): `internal/usecase/query.go`
- [Query language](https://github.com/t73fde/zettelstore/tree/master/internal/query): `internal/query`
- [Zettel model](https://github.com/t73fde/zettelstore/tree/master/internal/zettel): `internal/zettel`

### Storage and indexing

- [Box manager](https://github.com/t73fde/zettelstore/blob/master/internal/box/manager/manager.go): `internal/box/manager/manager.go`
- [Box interface](https://github.com/t73fde/zettelstore/blob/master/internal/box/box.go): `internal/box/box.go`
- [Directory storage](https://github.com/t73fde/zettelstore/blob/master/internal/box/dirbox/service.go): `internal/box/dirbox/service.go`
- [File and ZIP storage](https://github.com/t73fde/zettelstore/tree/master/internal/box/filebox): `internal/box/filebox`
- [Other box providers](https://github.com/t73fde/zettelstore/tree/master/internal/box): `internal/box`

### Content processing

- [Syntax parsers](https://github.com/t73fde/zettelstore/blob/master/internal/parser/parser.go): `internal/parser/parser.go`
- [Content evaluator](https://github.com/t73fde/zettelstore/tree/master/internal/evaluator): `internal/evaluator`

### Interfaces and output

- [Web interface](https://github.com/t73fde/zettelstore/tree/master/internal/web/adapter/webui): `internal/web/adapter/webui`
- [HTTP API](https://github.com/t73fde/zettelstore/tree/master/internal/web/adapter/webapi): `internal/web/adapter/webapi`
- [Content encoders](https://github.com/t73fde/zettelstore/tree/master/internal/encoder): `internal/encoder`

### Other components

- **User**

## Connections

- User → Command entry: starts
- Command entry → Service kernel: configures (evidence: `cmd/main.go`)
- Command entry → Box manager: creates (evidence: `cmd/main.go`)
- Command entry → Authentication: creates (evidence: `cmd/main.go`)
- Service kernel → HTTP server: starts (evidence: `internal/kernel/server.go`)
- User → HTTP server: sends requests
- HTTP server → HTTP routing: routes (evidence: `internal/web/server/router.go`)
- HTTP routing → Authentication: checks tokens (evidence: `internal/web/server/router.go`)
- HTTP routing → HTTP API: dispatches
- HTTP routing → Web interface: dispatches
- HTTP API → Zettel operations: invokes (evidence: `internal/web/adapter/webapi/query.go`)
- Web interface → Zettel operations: invokes
- Zettel operations → Box manager: accesses boxes
- Query execution → Box manager: selects metadata
- Query execution → Query language: executes directives (evidence: `internal/usecase/query.go`)
- Query execution → Content evaluator: evaluates items (evidence: `internal/usecase/query.go`)
- Box manager → Box interface: manages (evidence: `internal/box/manager/manager.go`)
- Box manager → Directory storage: coordinates (evidence: `internal/box/manager/manager.go`)
- Box interface → Directory storage: implemented by (evidence: `internal/box/dirbox/service.go`)
- Box interface → Other box providers: implemented by
- Directory storage → File and ZIP storage: uses (evidence: `internal/box/dirbox/service.go`)
- Zettel operations → Syntax parsers: parses notes
- Syntax parsers → Zettel model: produces parsed notes (evidence: `internal/parser/parser.go`)
- Content evaluator → Syntax parsers: uses parsed syntax (evidence: `internal/evaluator/inline.go`)
- Content evaluator → Box interface: retrieves linked notes (evidence: `internal/evaluator/inline.go`)
- HTTP API → Content encoders: formats responses
- Web interface → Content encoders: renders content
- Content encoders → Zettel model: encodes (evidence: `internal/encoder/mdenc.go`)
