archivr/ARCHIVR-MENTAL-MODEL.md

Archivr Mental Model

This document explains the current project shape after the workspace refactor.

The Big Model

Archivr is now a Rust workspace with three crates:

flowchart LR
  CLI["archivr-cli"] --> Core["archivr-core"]
  Server["archivr-server"] --> Core
  UI["static web UI"] --> Server
  ServerConfig["server TOML registry"] --> Server
  Core --> DB["archive/.archivr/archivr.sqlite"]
  Core --> Store["archive store: raw, raw_tweets, structured, temp"]

The key rule:

archivr-core owns archive behavior. archivr-cli and archivr-server are adapters.

Crates

Crate	Responsibility
archivr-core	Archive/domain logic, database schema, queries, download/store helpers
archivr-cli	Command-line interface, argument parsing, terminal behavior
archivr-server	Web server, API routes, mounted archive registry, static UI

Archive Model

Each archive is still self-contained:

some-archive/
  .archivr/
    archivr.sqlite
    name
    store_path
store/
  raw/
  raw_tweets/
  structured/
  temp/

The web server can mount many independent archives through its own TOML registry. That registry is separate from the archives themselves.

Example:

[[archives]]
id = "personal"
label = "Personal"
archive_path = "/path/to/archive/.archivr"

How To Run It

There are two user-facing binaries:

Binary	Purpose
archivr	CLI for initializing archives and capturing material into one archive
archivr-server	Web server for browsing one or more existing archives

The CLI writes archive data:

nix run .#archivr -- init ./my-archive --name "My Archive"
nix run .#archivr -- archive file:///absolute/path/to/file.pdf

The server reads archive data:

nix run .#archivr-server -- ./archivr-server.toml

If no config path is passed, the server reads ./archivr-server.toml. The config is a server registry, not archive data:

[[archives]]
id = "personal"
label = "Personal"
archive_path = "/absolute/path/to/my-archive/.archivr"

The packaged Nix server wrapper sets ARCHIVR_STATIC_DIR so the server can find the installed web UI assets. Source-tree runs do not need that variable because they fall back to crates/archivr-server/static.

Write Data Flow

When archiving something through the CLI:

sequenceDiagram
  participant User
  participant CLI
  participant Core
  participant Store
  participant DB

  User->>CLI: archivr archive path-or-url
  CLI->>Core: classify source and call downloader/store helpers
  Core->>Store: save raw/structured artifacts
  Core->>DB: insert run, source identity, entry, artifacts
  CLI->>User: terminal result

Read Data Flow

When opening the web UI:

sequenceDiagram
  participant Browser
  participant Server
  participant Core
  participant DB

  Browser->>Server: GET /api/archives
  Browser->>Server: GET /api/archives/:id/entries
  Server->>Core: list_root_entries(conn)
  Core->>DB: query archive SQLite
  DB-->>Core: rows
  Core-->>Server: summaries
  Server-->>Browser: JSON

Where To Edit

Feature kind	Edit here
DB schema, inserts, archive runs, entries, tags	crates/archivr-core/src/database.rs
Archive opening, listing entries, entry detail, runs	crates/archivr-core/src/archive.rs
Download/save behavior	crates/archivr-core/src/downloader/
CLI commands, argument parsing, terminal output	crates/archivr-cli/src/main.rs
Server API routes	crates/archivr-server/src/routes.rs
Mounted archive config model	crates/archivr-server/src/registry.rs
Browser UI behavior	crates/archivr-server/static/app.js
Browser UI layout	crates/archivr-server/static/index.html
Browser UI styling	crates/archivr-server/static/styles.css

Practical Feature Rule

If a feature affects archive truth, start in archivr-core.

If a feature is only how the terminal behaves, edit archivr-cli.

If a feature is only how the browser sees or calls things, edit archivr-server and the static UI.

If a browser feature needs new data, the usual order is:

1. Add or query the data in archivr-core.
2. Expose it in archivr-server.
3. Render it in the static UI.

Current Limitations

The web server reads archive data and serves the UI. It does not yet implement capture.

Search is currently simple client-side filtering.

Auth and session model: The server binds to 127.0.0.1 by default and has no authentication middleware. This is intentional — Archivr is a local tool. The bind address is configurable via the TOML bind field or ARCHIVR_BIND env var; a non-loopback address triggers a startup warning. Route families are classified (READ / ADMIN / WRITE / STATIC) in crates/archivr-server/src/routes.rs as the decision record for when middleware is eventually added. See the "Security and Deployment" section in docs/README.md.

Admin is a mounted-archives view, not a management system.