solpbc.org
personal memory agent
1# solstone-convey
2
3Web-based journal review interface built with Flask. It exposes a few small views for exploring daily summaries and entity data stored inside a **journal** folder.
4
5## Installation
6
7```bash
8make install
9```
10
11## Usage
12
13Run the server with:
14
15```bash
16convey
17```
18
19### Authentication
20
21Password authentication is configured via the CLI:
22
23```bash
24sol password set
25```
26
27When a password is set, it is stored as a secure hash in `config/journal.json` under `convey.password_hash`.
28
29If no password is set, the login page will prompt you to run `sol password set`.
30
31## Architecture
32
33Convey uses an **app plugin system** where all functional views are implemented as independent apps in the `/apps/` directory. The core `convey/` package provides authentication, WebSocket communication, and the app loading infrastructure.
34
35```
36convey/
37 __init__.py - Flask app factory, app registry, context processors
38 state.py - global state (journal_root)
39 bridge.py - Callosum WebSocket bridge for real-time events
40 utils.py - shared helpers (format_date, spawn_agent, etc.)
41 screenshot.py - screenshot utility for testing
42 views/
43 __init__.py - blueprint registration
44 home.py - authentication (login/logout) and root redirect
45 templates/
46 app.html - main app container template
47 menu_bar.html - dynamic left sidebar menu
48 status_pane.html - WebSocket status indicator
49 login.html - login page
50 macros.html - Jinja macros
51 static/ - shared CSS and JavaScript
52 app.css - app system styles
53 app.js - facet pills, services, notification center
54 websocket.js - WebSocket connection handler
55 error-handler.js - global error handling
56 colors.js - color palette
57 vendor/ - third-party libraries (marked.js)
58
59apps/ - App plugin directory (see APPS.md)
60 {app_name}/
61 app.json - metadata (icon, label)
62 routes.py - Flask blueprint with routes
63 workspace.html - main UI template
64 background.html - (optional) background service script
65```
66
67### App System
68
69All functional views are implemented as apps in `/apps/`. Each app:
70- Has its own directory with `app.json`, `routes.py`, and `workspace.html`
71- Uses blueprint name `app:{name}` with URL prefix `/app/{name}/`
72- Is automatically discovered and registered by `AppRegistry`
73- Can provide facet-scoped views and background services
74
75Browse `/apps/` to see available apps.
76
77### Core Routes
78
79The `convey/views/home.py` module provides essential routes:
80
81- `/` - Redirects to `/app/home/`
82- `/login` - Authentication page
83- `/logout` - Clear session and redirect to login
84- `/favicon.ico` - Serve favicon
85
86All functional views are accessed at `/app/{name}/` URLs.
87
88### Adding a New App
89
90See [APPS.md](APPS.md) for detailed instructions on creating new apps.