Architecture

C4Context title System Context — Lynx within joel.holmes.haus Person(admin, "Admin", "Uses the joel.holmes.haus UI to manage feeds and websites") Boundary(platform, "joel.holmes.haus Platform") { System(ui, "joel.holmes.haus", "Go-app WASM admin SPA") System(lynx, "Lynx", "Web feed and website archiving service") System(magpie, "Magpie", "Central resource index — receives website resources from Lynx") System(shrike, "Shrike", "Search — indexes enriched website text from Lynx") } SystemDb(postgres, "PostgreSQL", "Feeds, websites, and website metadata") SystemDb(minio, "MinIO / S3", "Archived HTML and readable text blobs") SystemQueue(kafka, "Kafka", "magpie.v1.Resource · shrike.v1.TextExtractedEvent") Rel(admin, ui, "Uses") Rel(ui, lynx, "ConnectRPC") Rel(lynx, postgres, "Reads / writes") Rel(lynx, minio, "Stores archived content") Rel(lynx, kafka, "Publishes resource events") Rel(kafka, magpie, "magpie.v1.Resource") Rel(kafka, shrike, "TextExtractedEvent")

C4Container title Lynx — Internal Containers Boundary(lynx, "Lynx") { Container(api, "cmd/api", "Go / ConnectRPC h2c :9000", "FeedService · WebsiteService · Enricher goroutine") Container(worker, "cmd/worker", "Go / Kafka", "FeedConsumer · WebsiteConsumer · Enricher pipeline goroutine") Container(ui, "cmd/ui", "Go-app WASM :8000", "Browser SPA — calls cmd/api via ConnectRPC HTTP client") Container(feedSvc, "feed.Service", "Go", "CRUD for feeds") Container(websiteSvc, "website.Service", "Go", "Create (publishes Kafka event) · CRUD") Container(enricher, "enrichment.Enricher", "Go / goroutine", "7-step pipeline: fetch → metadata → archive HTML → readable → archive → persist → magpie") ContainerDb(feedRepo, "FeedRepo", "PostgreSQL / squirrel", "feeds table") ContainerDb(websiteRepo, "WebsiteRepo + MetadataRepo", "PostgreSQL / squirrel", "websites · website_metadata tables") } SystemDb(postgres, "PostgreSQL", "") SystemDb(minio, "MinIO / S3", "websites/{uuid}/original.html · readable.txt") SystemQueue(kafka, "Kafka", "") Rel(api, feedSvc, "delegates") Rel(api, websiteSvc, "delegates") Rel(api, enricher, "Enqueue()") Rel(worker, feedSvc, "FeedConsumer") Rel(worker, websiteSvc, "WebsiteConsumer") Rel(worker, enricher, "Enqueue()") Rel(feedSvc, feedRepo, "CRUD") Rel(websiteSvc, websiteRepo, "CRUD") Rel(websiteSvc, kafka, "Publish magpie.v1.Resource") Rel(enricher, websiteRepo, "UpdateNameIfBlank · UpsertMetadata") Rel(enricher, minio, "PutObject") Rel(enricher, kafka, "TextExtractedEvent") Rel(feedRepo, postgres, "SQL") Rel(websiteRepo, postgres, "SQL")