{"id":50303695,"url":"https://github.com/rrbarrero/arch-review","last_synced_at":"2026-05-28T14:30:33.038Z","repository":{"id":353939200,"uuid":"1221479642","full_name":"rrbarrero/arch-review","owner":"rrbarrero","description":"LangGraph that can answer questions over technical documentation using Retrieval-Augmented Generation","archived":false,"fork":false,"pushed_at":"2026-04-26T10:05:32.000Z","size":281,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T11:25:18.644Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrbarrero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T09:09:49.000Z","updated_at":"2026-04-26T10:05:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rrbarrero/arch-review","commit_stats":null,"previous_names":["rrbarrero/arch-review"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rrbarrero/arch-review","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Farch-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Farch-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Farch-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Farch-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrbarrero","download_url":"https://codeload.github.com/rrbarrero/arch-review/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Farch-review/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33613431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T14:30:32.133Z","updated_at":"2026-05-28T14:30:33.031Z","avatar_url":"https://github.com/rrbarrero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arch Review\n\nArch Review is a cloud-native architecture review assistant for technical documentation and source code.\n\nIt solves a common engineering problem: architecture knowledge is usually spread across README files, Pulumi configuration, Kubernetes manifests, source code, migration files, and operational dashboards. That makes it difficult to answer simple but important questions such as \"how is this system deployed?\", \"which services store the retrieval context?\", or \"what trade-offs does this architecture make?\" without manually reading many files.\n\n![chat example](assets/chat-example.webp)\n\nThis project turns those technical sources into a queryable knowledge base. Users upload Markdown, Python, TypeScript, YAML, TOML, JSON, or text files; the backend validates and chunks them; the chunks are enriched with embeddings and graph context; and the chat interface answers questions using retrieval-augmented generation with source citations.\n\n## Product Surface\n\nThe application currently provides two main workflows:\n\n- **Document intake**: upload technical files from the browser, validate them, split them into retrieval-friendly chunks, generate embeddings, persist the documents and chunks in PostgreSQL with pgvector, and mirror chunk nodes into Neo4j.\n- **Architecture review chat**: ask questions about the ingested material through a Next.js chat UI. The frontend calls the FastAPI `/chat` endpoint, which retrieves relevant chunks and asks the LLM to answer only from the available evidence.\n\nLocal URLs:\n\n| Service | URL |\n| --- | --- |\n| Frontend | `http://localhost:3000` |\n| Backend API | `http://localhost:8000` |\n| Grafana | `http://localhost:3001` |\n| Prometheus | `http://localhost:9090` |\n| Loki | `http://localhost:3100` |\n\n## Architecture\n\nArch Review is organized as a small RAG platform with explicit application boundaries:\n\n1. The **Next.js frontend** provides a two-panel workspace: document intake on one side and the review chat on the other.\n2. The **FastAPI backend** exposes ingestion and chat endpoints.\n3. The **intake bounded context** validates files, creates domain `Document` and `DocumentChunk` entities, applies language-aware chunking, optionally builds hierarchical RAPTOR summaries, generates embeddings, writes relational/vector records, and creates graph nodes.\n4. The **chat bounded context** embeds the user question, retrieves similar chunks from pgvector, builds an evidence-constrained prompt, and returns an answer with structured citations.\n5. The **data layer** combines PostgreSQL/pgvector for durable document storage and semantic search with Neo4j for graph-oriented document relationships.\n6. The **operations layer** ships tracing, metrics, logs, dashboards, infrastructure automation, and Kubernetes deployment resources as part of the project.\n\nAt runtime, the main request flow looks like this:\n\n```text\nBrowser\n  -\u003e Next.js workspace\n  -\u003e FastAPI routers\n  -\u003e Application use cases\n  -\u003e Domain services\n  -\u003e PostgreSQL/pgvector, Neo4j, LLM/embedding provider\n  -\u003e Observability stack\n```\n\n## Backend Design\n\nThe Python backend follows a domain-driven structure:\n\n- `app/intake/domain`: document and chunk entities, value objects, repository contracts, chunking, embedding, and RAPTOR services.\n- `app/intake/application`: ingestion use case and DTOs.\n- `app/intake/infrastructure`: FastAPI routers, factories, PostgreSQL repositories, in-memory repositories for tests, and Neo4j integration.\n- `app/chat/domain`: retrieval and answer generation services.\n- `app/chat/application`: chat use case and DTOs.\n- `app/chat/infrastructure`: FastAPI router and dependency factory.\n\nThe key design choice is that business behavior lives in use cases and domain services, while FastAPI, PostgreSQL, Neo4j, and external LLM calls are kept behind infrastructure adapters. This keeps the ingestion and question-answering behavior testable without requiring every test to run the full platform.\n\n## Retrieval Design\n\nThe retrieval pipeline is built around evidence, traceability, and extensibility:\n\n- Uploaded files are validated by extension and size.\n- Content is split with language-specific strategies for Markdown, Python, and TypeScript, with a paragraph-based fallback for other supported text formats.\n- Chunks can be enriched with RAPTOR-style hierarchical summaries.\n- Embeddings are stored in PostgreSQL using pgvector.\n- Chat queries are embedded and matched against stored chunks using vector similarity.\n- The answer prompt instructs the LLM to answer only from retrieved context and to mention the filenames used.\n- The API returns citations containing the document id, chunk id, filename, snippet, and similarity score.\n\n## Frontend Design\n\nThe frontend is a Next.js application built around a practical review workspace rather than a landing page.\n\nIt uses:\n\n- `@assistant-ui/react` with a local runtime and custom model adapter connected to the FastAPI `/chat` endpoint.\n- React 19 and Next.js 16.\n- TypeScript and Zod for typed API and domain models.\n- Tailwind CSS, Radix UI primitives, and local UI components for the workspace and forms.\n- Vitest and Testing Library for frontend tests.\n\n\u003cimg src=\"assets/sidebar.webp\" alt=\"UI sidebar\" width=\"360\"\u003e\n\nThe UI keeps ingestion and conversation close together because architecture review is iterative: upload sources, ask a question, inspect citations, add more sources, and ask again.\n\n## Observability\n\nObservability is part of the architecture rather than an afterthought.\n\n| Component | Purpose |\n| --- | --- |\n| OpenTelemetry | Backend traces and instrumentation |\n| Tempo | Trace storage and querying |\n| Prometheus | Metrics scraping |\n| Grafana | Dashboards and visualization |\n| Loki | Structured log aggregation |\n\n![grafana-dashbaord](assets/grafana.webp)\n\nThe backend exposes Prometheus metrics at `/metrics/` and instruments FastAPI, HTTPX, psycopg, ingestion, retrieval, LLM answering, and business counters such as documents ingested, chunks created, chunks retrieved, and questions answered.\n\nThe same stack is available in Docker Compose for local development and through Pulumi-managed Kubernetes resources for the cluster deployment.\n\n## Infrastructure And Deployment\n\nThe project is designed to be reproducible from a fresh checkout.\n\n![grafana-dashbaord](assets/arch_review_deployment_architecture_v2.svg)\n\nIt includes:\n\n- Docker Compose for local development services.\n- Kind for local Kubernetes.\n- Pulumi for infrastructure as code.\n- Traefik as the Kubernetes ingress controller.\n- dbmate migrations for PostgreSQL schema management.\n- RustFS as an S3-compatible local backend used by the development infrastructure workflow.\n- Make targets for install, development, deployment, tests, and linting.\n\nUseful commands:\n\n```bash\nmake install\n```\n\nProvisions the local environment, starts supporting services, prepares Kubernetes and Pulumi resources, builds images, loads them into Kind, and deploys the application.\n\n```bash\nmake dev\n```\n\nStarts the local Docker Compose development loop, including the backend, frontend, PostgreSQL/pgvector, Neo4j, Tempo, Loki, Prometheus, and Grafana.\n\n```bash\nmake test\nmake lint\n```\n\nRuns backend tests and static checks.\n\n## Technologies\n\n| Area | Technologies |\n| --- | --- |\n| Backend API | Python 3.13, FastAPI, Pydantic Settings |\n| RAG and LLM | LangChain Ollama, LangGraph, embeddings, RAPTOR-style summaries |\n| Persistence | PostgreSQL, pgvector, psycopg, dbmate |\n| Graph | Neo4j |\n| Frontend | Next.js, React, TypeScript, assistant-ui, Zod, Tailwind CSS, Radix UI |\n| Observability | OpenTelemetry, Prometheus, Grafana, Tempo, Loki |\n| Infrastructure | Docker, Docker Compose, Kind, Kubernetes, Pulumi, Traefik, RustFS |\n| Quality | pytest, pytest-asyncio, Ruff, ty, Vitest, Testing Library, ESLint, Prettier |\n\n## Patterns\n\nThe project intentionally demonstrates several architectural patterns:\n\n- **Domain-Driven Design**: separate bounded contexts for intake and chat, with entities, value objects, repositories, services, use cases, DTOs, and infrastructure adapters.\n- **Ports and adapters**: repository interfaces and services isolate application behavior from PostgreSQL, Neo4j, and external LLM infrastructure.\n- **Retrieval-Augmented Generation**: answers are generated from retrieved chunks rather than from unconstrained model memory.\n- **Hierarchical retrieval preparation**: RAPTOR-style summaries can add higher-level context above raw chunks.\n- **Infrastructure as Code**: Pulumi defines the Kubernetes application and observability resources.\n- **Operational observability**: traces, metrics, logs, and dashboards are included in the normal development and deployment paths.\n- **Reproducible local platform**: Make targets coordinate Docker Compose, Kind, migrations, Pulumi, and image loading.\n\n## Example Usage\n\nAfter ingesting the project documentation and configuration files, a user can ask:\n\n```text\nSummarize the architecture described in the ingested documents.\n```\n\nExample answer:\n\n```text\nThe architecture described in the documents is a cloud-native LLM application built on Kubernetes, designed for reproducible deployment and observability. Key components and configurations include:\nCore Services \u0026 Configuration\n\n    Application Stack\n        API Service: arch-review-api (Port 8000, Image arch-review:dev, Replica 1), managed via Traefik ingress (HTTP/HTTPS ports 30080/30443).\n        Frontend: arch-review-frontend (Port 3000), linked to the API via Traefik.\n        Database:\n            PostgreSQL/pgvector: Port 5432, Storage 256Mi, Image pgvector/pgvector:pg16, DB/User pgvector_db/pgvector_user linked to arch_review.\n            Neo4j: Ports 7474 (HTTP), 7687 (Bolt), Image neo4j:5-community, Storage 256Mi.\n        Observability Stack:\n            Tempo: OTLP traces (Ports 3200, 4317, 4318).\n            Loki/Prometheus/Grafana: Logs, metrics, and dashboards (Grafana Host: grafana.arch-review.local).\n\n    Networking \u0026 Security\n        Traefik: Ingress controller with explicit port assignments (traefik_http_node_port, traefik_https_node_port), Ingress Class traefik.\n        Encryption: Versioned salts (v1:JDVXG0inRtQ=) and unversioned salt (VCq7Emqf00ybfpTlhkDoBVUzzaSuUA==).\n\n    Deployment\n        Kubernetes: Managed via Pulumi (ConfigMaps, Deployments, Services).\n        Local Development: Docker Compose for dev stack (observability + frontend).\n        Production: Kubernetes with Traefik Ingress for Grafana.\n\nTechnical Architecture\n\n    Document Ingestion: Markdown/Python files are validated, split into chunks, embedded via PostgreSQL/pgvector, and mirrored to Neo4j for knowledge graph storage.\n    RAG Integration: Semantic search via pgvector, with POST /chat endpoint for retrieval-augmented generation (RAG).\n    Observability:\n        Traces: OpenTelemetry (OTLP to Tempo) with custom spans.\n        Metrics: Prometheus scrapes /metrics/ endpoints.\n        Logs: Structured logging with trace/span correlation to Loki.\n    Testing \u0026 CI/CD: Integration tests for chat, HTTP contracts, and automated linting/migration checks.\n\nKey Decisions\n\n    Single-replica deployments for simplicity.\n    Traefik as ingress controller with explicit port mappings.\n    Standardized ports (e.g., PostgreSQL 5432, Grafana 3000) for compatibility.\n    Development tags (:dev) for non-production.\n    Infrastructure-as-Code (Pulumi) for reproducible Kubernetes deployments.\n\nCode/Infrastructure References\n\n    Tools: FastAPI, Next.js, PostgreSQL/pgvector, Neo4j, OpenTelemetry, Prometheus, Loki, Tempo, Pulumi, Traefik.\n    Deployments: Docker Compose (local), Kubernetes (production).\n    Services: FastAPI, httpx, psycopg, embedding service, chunk repository.\n\nSources: Pulumi.dev.yaml (encryption, services, Traefik), README.md (RAG, observability, deployment workflows).\n\nSources:\n\n    Pulumi.dev.yaml · chunk 96091535ce7f43bcae8eeef5069a68cb · score 0.43\n    README.md · chunk 73d61dc9b5d24373a48192538a4bb887 · score 0.44\n    README.md · chunk 1da2538363704ab48db2900bf7fda2c9 · score 0.50\n    README.md · chunk b3d677cf16df42fa94c3892c52c402d2 · score 0.50\n    Pulumi.dev.yaml · chunk d93777289e1e4abba1599ff028b156a7 · score 0.50\n    README.md · chunk 3c8197be8e44469dac42a3fa6ab481fd · score 0.49\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbarrero%2Farch-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrbarrero%2Farch-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbarrero%2Farch-review/lists"}