1
Fork 0
mirror of https://github.com/thegeneralist01/archivr synced 2026-07-21 18:55:36 +02:00

feat: add db and multi-archive web UI foundation (#8)

* Add SQLite metadata database support

* Implement archive metadata database

* chore: let's guess cargoHash because there's something wrong with nixpkgs!

* Gate test-only database helpers behind cfg(test)

* Fix archive database row identity

* Use serde for archive metadata JSON

* Finalize archive runs at command level

* Handle archive command errors without panics

* Cover tweet entry metadata recording

* Document static regex invariants

* docs: add web UI design spec

* docs: add web UI implementation plan

* chore: move cli into workspace crate

* chore: track workspace crates directory

* refactor: extract archive core crate

* refactor: add core archive opening APIs

* refactor: rename taxonomy model to tags

* feat: add archive query APIs

* feat: add web server registry

* feat: expose archive server APIs

* feat: add archive table web UI

* fix: complete web UI smoke path

* docs: add architecture mental model

* docs: remove private superpowers plans

* nix: split cli and server packages

* chore: remove PLAN.md
This commit is contained in:
TheGeneralist 2026-06-14 00:27:16 +02:00 committed by GitHub
parent cc380ec5ba
commit b56c969624
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 3928 additions and 171 deletions

135
ARCHIVR-MENTAL-MODEL.md Normal file
View file

@ -0,0 +1,135 @@
# 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:
```mermaid
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:
```text
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:
```toml
[[archives]]
id = "personal"
label = "Personal"
archive_path = "/path/to/archive/.archivr"
```
## Write Data Flow
When archiving something through the CLI:
```mermaid
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:
```mermaid
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 is not a production model yet.
Admin is a mounted-archives view, not a management system.