Architecture

C4Context title System Context — Owl within joel.holmes.haus Person(admin, "Admin", "Manages personal library of books and academic papers") Boundary(platform, "joel.holmes.haus Platform") { System(ui, "joel.holmes.haus", "Go-app WASM admin SPA") System(owl, "Owl", "Personal digital library — books and academic papers") System(magpie, "Magpie", "Resource hub — receives book and paper resources from Owl") System(shrike, "Shrike", "Search — indexes paper/book text via TextExtractedEvent") } SystemDb(postgres, "PostgreSQL", "Books, papers, book metadata") SystemDb(minio, "MinIO / S3", "PDF and book file blobs") SystemQueue(kafka, "Kafka", "owl.v1.Paper · owl.v1.Book · magpie.v1.Resource · shrike.v1.TextExtractedEvent") System_Ext(arxiv, "arXiv / CrossRef", "Academic paper metadata APIs") System_Ext(googlebooks, "Google Books / Open Library", "Book metadata APIs (enrichment)") Rel(admin, ui, "Uses") Rel(ui, owl, "ConnectRPC") Rel(owl, postgres, "Reads / writes") Rel(owl, minio, "Stores PDFs and book files") Rel(owl, kafka, "Publishes paper and book events") Rel(owl, arxiv, "Resolves DOI / arXiv metadata") Rel(owl, googlebooks, "Enriches book metadata") Rel(kafka, magpie, "magpie.v1.Resource") Rel(kafka, shrike, "TextExtractedEvent")

C4Container title Owl — Internal Containers Boundary(owl, "Owl") { Container(api, "cmd/api", "Go / ConnectRPC h2c :9000", "BookService · PaperService · in-process Ingester goroutine") Container(worker, "cmd/worker", "Go / Kafka", "BookConsumer · PaperConsumer · Ingester pipeline · BookIngester pipeline") Container(bookSvc, "book.Service", "Go", "CRUD for books") Container(paperSvc, "paper.Service", "Go", "CRUD for papers · IngestPaperByURL · GetIngestionStatus") Container(ingester, "ingestion.Ingester", "Go / goroutine", "7-step paper pipeline: resolve → download → metadata → dedup → upload → persist → magpie") Container(bookIngester, "ingestion.BookIngester", "Go / goroutine", "4-step book pipeline: download → dedup → upload → persist") Container(metaClient, "metadata.CompositeClient", "Go / HTTP", "ArxivClient + CrossRefClient for DOI/arXiv resolution") ContainerDb(bookRepo, "BookRepo + BookMetadataRepo", "PostgreSQL / squirrel", "books · book_metadata tables") ContainerDb(paperRepo, "PaperRepo", "PostgreSQL / squirrel", "papers table") } SystemDb(postgres, "PostgreSQL", "") SystemDb(minio, "MinIO / S3", "papers/CHECKSUM · books/CHECKSUM") SystemQueue(kafka, "Kafka", "") System_Ext(arxiv, "arXiv / CrossRef", "") Rel(api, bookSvc, "delegates") Rel(api, paperSvc, "delegates") Rel(api, ingester, "Enqueue() / Status()") Rel(kafka, worker, "owl.v1.Book · owl.v1.Paper") Rel(worker, bookSvc, "BookConsumer") Rel(worker, paperSvc, "PaperConsumer") Rel(worker, ingester, "Enqueue()") Rel(worker, bookIngester, "Enqueue()") Rel(ingester, paperRepo, "Create") Rel(ingester, minio, "Upload PDF") Rel(ingester, kafka, "magpie.v1.Resource") Rel(ingester, metaClient, "Resolve DOI / arXiv") Rel(bookIngester, bookRepo, "Create") Rel(bookIngester, minio, "Upload book file") Rel(bookRepo, postgres, "SQL") Rel(paperRepo, postgres, "SQL")