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:
69
CLAUDE.md
Normal file
69
CLAUDE.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## Overview
|
||||
|
||||
MCQ (Metacircular Document Queue) is a reading queue service. Documents
|
||||
(raw markdown) are pushed via API from inside the infrastructure, then
|
||||
read through a mobile-friendly web UI from anywhere. MCIAS authenticates
|
||||
all access — any user (including guest) can read, any user (including
|
||||
system accounts) can push.
|
||||
|
||||
## Build Commands
|
||||
|
||||
```bash
|
||||
make all # vet → lint → test → build
|
||||
make mcq # build binary with version injection
|
||||
make build # go build ./...
|
||||
make test # go test ./...
|
||||
make vet # go vet ./...
|
||||
make lint # golangci-lint run ./...
|
||||
make proto # regenerate gRPC code from .proto files
|
||||
make proto-lint # buf lint + buf breaking
|
||||
make devserver # build and run locally against srv/mcq.toml
|
||||
make clean # remove binaries
|
||||
```
|
||||
|
||||
Run a single test:
|
||||
```bash
|
||||
go test ./internal/db/ -run TestPutDocument
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
Single binary, three concerns:
|
||||
|
||||
- **REST API** (`/v1/*`) — CRUD for documents, MCIAS Bearer token auth
|
||||
- **gRPC API** (`:9443`) — same operations, MCIAS interceptor auth
|
||||
- **Web UI** (`/`, `/d/{slug}`, `/login`) — goldmark-rendered reader, MCIAS session cookies
|
||||
|
||||
Documents keyed by slug (unique). PUT upserts — same slug replaces content.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
cmd/mcq/ CLI entry point (server subcommand)
|
||||
internal/
|
||||
db/ SQLite schema, migrations, document CRUD
|
||||
server/ REST API routes and handlers
|
||||
grpcserver/ gRPC server, interceptors, service handlers
|
||||
webserver/ Web UI routes, templates, session management
|
||||
render/ goldmark markdown-to-HTML renderer
|
||||
proto/mcq/v1/ Protobuf definitions
|
||||
gen/mcq/v1/ Generated Go code (do not edit)
|
||||
web/ Embedded templates + static files
|
||||
deploy/ systemd, examples
|
||||
```
|
||||
|
||||
## Shared Library
|
||||
|
||||
MCQ uses `mcdsl` (git.wntrmute.dev/mc/mcdsl) for: auth, db, config,
|
||||
httpserver, grpcserver, csrf, web (session cookies, auth middleware,
|
||||
template rendering).
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **REST/gRPC sync**: Every REST endpoint has a corresponding gRPC RPC.
|
||||
2. **gRPC interceptor maps**: New RPCs must be added to the correct map.
|
||||
3. **No test frameworks**: stdlib `testing` only, real SQLite in t.TempDir().
|
||||
4. **CSRF on all web mutations**: double-submit cookie pattern.
|
||||
5. **Session cookies**: HttpOnly, Secure, SameSite=Strict.
|
||||
Reference in New Issue
Block a user