Architecture

C4Context title System Context — Shrike within joel.holmes.haus Boundary(platform, "joel.holmes.haus Platform") { System(ui, "joel.holmes.haus", "Go-app WASM admin SPA — submits search queries") System(shrike, "Shrike", "Full-text and semantic search indexing service") System(lynx, "Lynx", "Web archiving — publishes TextExtractedEvent after enrichment") System(greyseal, "Grey Seal", "RAG conversations — queries Shrike for context retrieval") System(magpie, "Magpie", "Resource index — publishes Resource events for indexing") } SystemDb(postgres, "PostgreSQL", "Index records and full-text document store") SystemDb(qdrant, "Qdrant", "Vector store — cosine similarity search (768-dim)") System_Ext(ollama, "Ollama", "Local LLM — nomic-embed-text embeddings") SystemQueue(kafka, "Kafka", "TextExtractedEvent · EnvelopeEvent · ImportRequest · magpie.v1.Resource") Rel(ui, shrike, "ConnectRPC search queries") Rel(greyseal, shrike, "ConnectRPC hybrid search") Rel(lynx, kafka, "Publishes TextExtractedEvent") Rel(magpie, kafka, "Publishes magpie.v1.Resource") Rel(shrike, postgres, "Reads / writes index records") Rel(shrike, qdrant, "Vector upsert / search") Rel(shrike, ollama, "Embed text chunks") Rel(kafka, shrike, "TextExtractedEvent · EnvelopeEvent · ImportRequest · magpie.v1.Resource")

C4Container title Shrike — Internal Containers Boundary(shrike, "Shrike") { Container(api, "cmd/api", "Go / ConnectRPC h2c :9000", "IndexRecordService (CRUD) · SearchService (semantic + keyword + reindex)") Container(worker, "cmd/worker", "Go / Kafka", "4 consumers: TextExtracted · Envelope · Import · Resource") Container(indexSvc, "index_record.Service", "Go", "CRUD for index records") Container(chunker, "lib/chunker", "Go", "512-word overlapping windows, 64-word overlap") Container(embedder, "OllamaEmbedder", "Go / HTTP", "nomic-embed-text via Ollama REST API") Container(vectorStore, "QdrantStore", "Go / HTTP", "Upsert · Search · DeleteByEntity on shrike_context collection") ContainerDb(indexRepo, "IndexRecordRepo + DocumentRepo", "PostgreSQL / squirrel", "indexrecords (tsvector GIN) · documents tables") } SystemDb(postgres, "PostgreSQL", "") SystemDb(qdrant, "Qdrant", "shrike_context collection, 768-dim cosine") System_Ext(ollama, "Ollama", "http://ollama:11434") SystemDb(minio, "MinIO / S3", "Blob source for ImportConsumer") SystemQueue(kafka, "Kafka", "") Rel(api, indexSvc, "delegates CRUD") Rel(api, chunker, "Reindex path") Rel(api, embedder, "Embed query") Rel(api, vectorStore, "Search / DeleteByEntity") Rel(api, indexRepo, "Keyword search (tsvector)") Rel(kafka, worker, "TextExtractedEvent · EnvelopeEvent · ImportRequest · magpie.v1.Resource") Rel(worker, indexSvc, "Upsert index records") Rel(worker, chunker, "Chunk full text") Rel(worker, embedder, "Embed chunks") Rel(worker, vectorStore, "Upsert points") Rel(worker, minio, "Download blobs (ImportConsumer)") Rel(indexRepo, postgres, "SQL") Rel(embedder, ollama, "POST /api/embed") Rel(vectorStore, qdrant, "HTTP REST")