mc/mcq

Files

Kyle Isom bc1627915e 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>

2026-03-28 11:53:26 -07:00

2.3 KiB

Raw Blame History

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

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:

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

REST/gRPC sync: Every REST endpoint has a corresponding gRPC RPC.
gRPC interceptor maps: New RPCs must be added to the correct map.
No test frameworks: stdlib testing only, real SQLite in t.TempDir().
CSRF on all web mutations: double-submit cookie pattern.
Session cookies: HttpOnly, Secure, SameSite=Strict.

2.3 KiB Raw Blame History