Initial implementation of mcq — document reading queue
Single-binary service: push raw markdown via REST/gRPC API, read rendered HTML through mobile-friendly web UI. MCIAS auth on all endpoints, SQLite storage, goldmark rendering with GFM and syntax highlighting. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
90
ARCHITECTURE.md
Normal file
90
ARCHITECTURE.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# MCQ Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
MCQ is a document reading queue. Push raw markdown from inside the
|
||||
infrastructure, read rendered HTML on any device via the web UI.
|
||||
|
||||
## System Context
|
||||
|
||||
```
|
||||
Push clients (curl, scripts, Claude remote)
|
||||
│
|
||||
▼ PUT /v1/documents/{slug}
|
||||
┌─────────┐ ┌──────────┐
|
||||
│ MCQ │────▶│ MCIAS │ auth validation
|
||||
│ :8443 │◀────│ :8443 │
|
||||
└─────────┘ └──────────┘
|
||||
│
|
||||
▼ SQLite
|
||||
┌─────────┐
|
||||
│ mcq.db │
|
||||
└─────────┘
|
||||
|
||||
Browser (phone, desktop)
|
||||
│
|
||||
▼ GET / → login → reading queue → /d/{slug}
|
||||
┌─────────┐
|
||||
│ MCQ │
|
||||
│ web UI │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
## Data Model
|
||||
|
||||
Single table:
|
||||
|
||||
```sql
|
||||
CREATE TABLE documents (
|
||||
id INTEGER PRIMARY KEY,
|
||||
slug TEXT NOT NULL UNIQUE,
|
||||
title TEXT NOT NULL,
|
||||
body TEXT NOT NULL, -- raw markdown
|
||||
pushed_by TEXT NOT NULL, -- MCIAS username
|
||||
pushed_at TEXT NOT NULL, -- RFC 3339 UTC
|
||||
read INTEGER NOT NULL DEFAULT 0
|
||||
);
|
||||
```
|
||||
|
||||
Slug is the identity key. PUT with the same slug replaces content and
|
||||
resets the read flag.
|
||||
|
||||
## API
|
||||
|
||||
### REST (Bearer token auth)
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| POST | /v1/auth/login | Public | Get bearer token |
|
||||
| POST | /v1/auth/logout | Auth | Revoke token |
|
||||
| GET | /v1/health | Public | Health check |
|
||||
| GET | /v1/documents | Auth | List all documents |
|
||||
| GET | /v1/documents/{slug} | Auth | Get document |
|
||||
| PUT | /v1/documents/{slug} | Auth | Create or update |
|
||||
| DELETE | /v1/documents/{slug} | Auth | Remove document |
|
||||
| POST | /v1/documents/{slug}/read | Auth | Mark read |
|
||||
| POST | /v1/documents/{slug}/unread | Auth | Mark unread |
|
||||
|
||||
### gRPC
|
||||
|
||||
DocumentService, AuthService, AdminService — mirrors REST exactly.
|
||||
|
||||
### Web UI (session cookie auth)
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| /login | MCIAS login form |
|
||||
| / | Document list (queue) |
|
||||
| /d/{slug} | Rendered markdown reader |
|
||||
|
||||
## Security
|
||||
|
||||
- MCIAS auth on all endpoints (REST: Bearer, Web: session cookie, gRPC: interceptor)
|
||||
- CSRF double-submit cookies on all web mutations
|
||||
- TLS 1.3 minimum
|
||||
- Default-deny on unmapped gRPC methods
|
||||
|
||||
## Rendering
|
||||
|
||||
Goldmark with GFM extensions, Chroma syntax highlighting, auto heading IDs.
|
||||
Markdown stored raw in SQLite, rendered to HTML on each page view.
|
||||
Reference in New Issue
Block a user