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:
parent
cc380ec5ba
commit
b56c969624
25 changed files with 3928 additions and 171 deletions
135
ARCHIVR-MENTAL-MODEL.md
Normal file
135
ARCHIVR-MENTAL-MODEL.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue