Groundwork v2 is an enterprise-grade, distributed AI Document Intelligence & Knowledge Platform. Moving beyond basic PDF chat, Groundwork v2 offers workspace isolation, structured document artifact extraction, multi-document diff & spec comparison, AI senior engineer architectural reviewing, D3 force-directed knowledge graphs, and hybrid retrieval with cross-encoder reranking.
📖 Complete Product & Technical Handbook: For exhaustive architectural diagrams, Flyway DDL schemas, REST API payloads, UI design system rules, and deployment guides, see HANDBOOK.md.
- 🗂️ Multi-Workspace Management (
/api/workspaces): Logical workspace isolation enabling teams to segment project documentation, compliance specs, and architecture decisions cleanly. - 📋 Document Intelligence Artifact Extractor (
/api/artifacts): Automated extraction of structured JSON artifacts across 7 categories: Functional & Non-Functional Requirements, API Specs, Risk Registers, Architecture Decisions (ADRs), Assumptions, and Glossary Terms. - ⚔️ Multi-Document Comparison Studio (
/api/compare): Side-by-side spec comparison detecting 5 diff types (Added, Removed, Modified, Breaking Changes, Ambiguous), with automated risk scoring and AI synthesis. - 🔍 AI Senior Engineer Reviewer & Gap Analysis (
/api/review): Architectural quality audits evaluating Security, Scalability, Consistency, Contradictions, and Missing Requirements with severity ratings (Critical 🔴, High 🟧, Medium 🟨, Low 🟦). - 🌐 Interactive D3.js Force Knowledge Graph (
/api/graph): Dynamic 2D graph visualizer rendering entities, APIs, documents, and relationships (USES, CALLS, DEPENDS_ON, IMPLEMENTS) with node category filtering and node inspector drawer. - 🏷️ Scoped
@Document Mention Tagging: Restrict RAG retrieval to specific uploaded documents by typing@in the chat prompt for pinpoint precision.
Groundwork follows Hexagonal Architecture (Ports and Adapters) to isolate core domain logic from external LLM providers, search indexers, and web delivery layers.
graph TD
User([Browser Client / CLI]) -->|HTTP / SSE Streaming| Frontend[Tailwind v3 + TypeScript + D3 UI]
Frontend -->|REST API / SSE| Gateway[Spring Security + JWT Auth Filter]
subgraph Spring Boot Application Core
Gateway --> Interceptor[Bucket4j Rate Limiter Interceptor]
Interceptor --> WorkspaceCtrl[Workspace & Module Controllers]
WorkspaceCtrl --> ExtractionSvc[Structured Extraction Engine]
WorkspaceCtrl --> Guardrail[Prompt Injection Guardrail]
Guardrail --> RetrievalService[Retrieval Service]
subgraph Hybrid Search Engine
RetrievalService -->|Vector Search 1536d| PgVector[(PostgreSQL + pgvector)]
RetrievalService -->|TSVector GIN Index| PgFTS[(PostgreSQL Full-Text Search)]
RetrievalService -->|RRF Fusion k=60| RRF[Reciprocal Rank Fusion Engine]
RRF -->|Rerank Candidates| Cohere[Cohere Rerank API Adapter]
end
subgraph Tool & Function Calling
WorkspaceCtrl -->|Spring AI Function Calling| SupportTools[Support Tools Suite]
SupportTools -->|Resilience4j Circuit Breaker| ExternalAPI[Third-Party APIs]
end
subgraph Distributed Cache & Lock Layer
RetrievalService <-->|10m Cache TTL| Redis[(Redis Cluster)]
WorkspaceCtrl <-->|Async Job Lock| DBIndex[(Postgres Partial Unique Index)]
end
end
WorkspaceCtrl -->|Grounded System Prompt| LLM[Gemini 1.5 / OpenAI GPT-4o]
LLM -->|Streamed SSE Response| Frontend
- Dense Vector Search: 1536-dimensional embeddings indexed with HNSW for semantic query understanding.
-
Sparse Full-Text Search: PostgreSQL
tsvectorwith GIN indexing for exact technical identifier lookup (ERR_403_SIGNATURE, API paths). -
Reciprocal Rank Fusion (RRF): Merges vector and keyword candidate lists without score normalization bias:
$$\text{RRF}(d) = \sum_{m \in M} \frac{1}{k + r_m(d)} \quad (k = 60)$$ - Cohere Cross-Encoder Reranking: Re-orders candidate chunks using Cohere's Rerank API for maximum precision.
- Redis Caching Layer: 10-minute TTL for candidate retrieval lists, 30-day TTL for computed vector embeddings.
- DB-Level Distributed Lock: Prevents concurrent async re-indexing jobs via partial unique index (
idx_single_active_job), returning an instant 409 Conflict response.
| Retrieval Mode | Context Precision | Context Recall | Faithfulness | Answer Relevancy | Avg Latency (ms) |
|---|---|---|---|---|---|
| Naive Vector Search | 0.68 | 0.72 | 0.81 | 0.79 | 420 ms |
| Hybrid + RRF + Cohere Rerank | 0.94 | 0.96 | 0.98 | 0.95 | 180 ms (Cached) |
GET /api/workspaces: List all active workspaces.POST /api/workspaces: Create a new workspace (name,description).DELETE /api/workspaces/{id}: Delete workspace and associated documents.
POST /api/chat: Send query with optional@doc_nametag and retrieval mode.GET /api/chat/stream: Real-time Server-Sent Events (SSE) streaming tokens.
POST /api/artifacts/extract?title=...: Trigger structured JSON extraction.GET /api/artifacts: List extracted requirements, APIs, risks, and decisions.
POST /api/compare: Compare 2 documents (docATitle,docBTitle). Returns diff matrix & risk score.
POST /api/graph/build: Extract entity & relationship nodes from workspace documents.GET /api/graph/{workspaceId}: Get D3 node-link JSON network graph.
POST /api/review: Execute architectural quality audit.GET /api/review/reports: Fetch review findings sorted by severity.
git clone git@github.com:Lalithsha/Groundwork.git
cd Groundwork
docker compose up --build -dAccess the application UI at http://localhost:5173 and the Spring Boot backend at http://localhost:8080.
./dev.shThis project is licensed under the MIT License.