Architecture

C4Context title System Context — Magpie within joel.holmes.haus Person(admin, "Admin", "Manages resources, tags, and labels via the UI") Boundary(platform, "joel.holmes.haus Platform") { System(ui, "joel.holmes.haus", "Go-app WASM admin SPA") System(magpie, "Magpie", "Central resource index — stores and fans out resource metadata") System(lynx, "Lynx", "Web archiving — publishes website resources") System(owl, "Owl", "Library — publishes book and paper resources") System(greyseal, "Grey Seal", "RAG service — consumes resources for conversation context") System(shrike, "Shrike", "Search — receives resource events for keyword indexing") } SystemDb(postgres, "PostgreSQL", "Resources, tags, labels, resource_tags, resource_labels") SystemQueue(kafka, "Kafka", "magpie.v1.Resource (inbound + outbound) · greyseal.v1.Resource") Rel(admin, ui, "Uses") Rel(ui, magpie, "ConnectRPC") Rel(lynx, magpie, "Publishes magpie.v1.Resource") Rel(owl, magpie, "Publishes magpie.v1.Resource") Rel(magpie, postgres, "Reads / writes") Rel(kafka, magpie, "inbound magpie.v1.Resource") Rel(magpie, kafka, "outbound greyseal.v1.Resource") Rel(kafka, greyseal, "greyseal.v1.Resource") Rel(kafka, shrike, "magpie.v1.Resource")

C4Container title Magpie — Internal Containers Boundary(magpie, "Magpie") { Container(api, "cmd/api", "Go / ConnectRPC h2c :9000", "5 domain handlers: Resource · Tag · Label · ResourceTag · ResourceLabel") Container(worker, "cmd/worker", "Go / Kafka", "5 domain consumers; ResourceConsumer also republishes to grey-seal topic") Container(ui, "cmd/ui", "Go-app WASM :8000", "Browser SPA — resource list, tag/label management") Container(resourceSvc, "resource.Service", "Go", "Create · List · Get · Delete") Container(tagSvc, "tag.Service", "Go", "CRUD for tags") Container(labelSvc, "label.Service", "Go", "CRUD for labels") Container(rtSvc, "resource_tag.Service", "Go", "Manage tag associations") Container(rlSvc, "resource_label.Service", "Go", "Manage label associations") ContainerDb(resourceRepo, "ResourceRepo", "PostgreSQL / squirrel", "resources table (ON CONFLICT uuid DO NOTHING)") ContainerDb(tagRepo, "TagRepo + LabelRepo + join repos", "PostgreSQL / squirrel", "tags · labels · resource_tags · resource_labels") } SystemDb(postgres, "PostgreSQL", "") SystemQueue(kafka, "Kafka", "consumer group app-1") Rel(api, resourceSvc, "delegates · publishes Kafka event on Create") Rel(api, tagSvc, "delegates") Rel(api, labelSvc, "delegates") Rel(api, rtSvc, "delegates") Rel(api, rlSvc, "delegates") Rel(kafka, worker, "magpie.v1.Resource") Rel(worker, resourceSvc, "Upsert resource") Rel(worker, kafka, "Publishes greyseal.v1.Resource") Rel(resourceSvc, resourceRepo, "CRUD") Rel(tagSvc, tagRepo, "CRUD") Rel(resourceRepo, postgres, "SQL") Rel(tagRepo, postgres, "SQL")