Phoenix is a Transparent Self-Healing Hybrid RAG system designed specifically for technical documentation (such as codebase references, configuration properties, and API manuals).
Built using Spring Boot 3.3.x, FastAPI, and React 19, Phoenix bridges the "trust gap" inherent in black-box AI retrieval systems by making the entire retrieval, scoring, reranking, and fallback process fully observable and traceable for engineers.
Note: Phoenix runs entirely locally by design — see Setup & Running Locally below. No hosted demo is provided.
Figure 1: A design mockup of the Phoenix Investigation Console interface visualizing RAG retrieval scores, consensus Jaccard agreement metrics, and active fallback pipelines.
- Beyond the Black Box
- Designing for Failure
- Beyond an API Call
- Local Intelligence
- Why One Backend Isn't Enough
- ENGINEERING JOURNEY
Traditional Retrieval-Augmented Generation (RAG) systems fail in technical workspaces for three key reasons:
- The Alphanumeric Precision Gap: Pure semantic vector search (cosine similarity on dense embeddings) frequently misses exact-match property keys, configuration properties (such as
spring.jpa.hibernate.ddl-auto), or error codes, returning conceptually related but incorrect contexts. - The "Black Box" Trust Gap: When an AI answers incorrectly, developers cannot diagnose whether the breakdown occurred during database retrieval, fusion, reranking, or LLM synthesis.
- Hallucinations on Weak Context: Generic RAG systems attempt to generate answers even when search matches return zero relevant context.
Phoenix resolves these issues by combining a hybrid search engine with a self-healing fallback state machine, while rendering the entire pipeline's reasoning path in real-time.
A FastAPI-driven orchestrator state machine dynamically manages query degradation. If initial retrieval scores are weak, the system automatically rewrites queries, escalates to Cross-Encoder reranking, or falls back to interactive clarification prompts to avoid hallucinations.
Combines semantic dense vector search (PostgreSQL pgvector with all-MiniLM-L6-v2) and sparse keyword search (Custom Tokenizer + BM25 ranking) using a Weighted Linear Combination (WLC) MinMaxScaler score fusion (
Calculates semantic consensus across retrieved text segments. By evaluating MaxSim metrics and agreement scores among top chunks, the engine quantifies response reliability before synthesis occurs.
An interactive, collapsible timeline that maps the exact lifecycle of a query. Developers can inspect routing paths, query rewrites, raw cosine similarities, BM25 scores, and final confidence levels in a terminal-like build log.
Row-level JPA query boundaries and Spring Security token interceptors ensure absolute project separation. Users can only search, upload, or manage documents within their own workspace namespaces.
The following diagram maps the execution flow of a user query through the self-healing hybrid retrieval pipeline:
[React Frontend Console]
│
▼ (REST/JWT)
[Spring Boot Gateway Service]
│
▼ (Async REST /internal/v1/process)
[FastAPI Retrieval Engine] ◄────────────────────────────────┐
│ │
├─► [Vector Search Service] ──► pgvector │
├─► [Keyword Search Service] ──► BM25 │ (Fallback Loop:
│ │ CS < 0.75)
▼ (Score Fusion & CS Calculation) │
[Composite Confidence Score (CS)] │
│ │
├─► [Green Path (CS >= 0.75)] ──► Ollama (Mistral)│
├─► [Yellow Path (CS 0.50-0.75)] ──► LLM Rewrite ─┘
├─► [Orange Path (CS 0.35-0.50)] ──► FlashRank Cross-Encoder
└─► [Red Path (CS < 0.35)] ────────► Clarification Prompt
- Frontend Console: React 19 (Vite compilation), Zustand, Tailwind CSS, Framer Motion, react-markdown.
- API Gateway Service: Java 21, Spring Boot 3.3.1, Spring Security, Hibernate ORM, Flyway Schema Migrations.
- AI & Retrieval Engine: Python 3.11, FastAPI, SQLAlchemy ORM,
pgvector,SentenceTransformers(all-MiniLM-L6-v2),rank_bm25(Okapi model),FlashRankCross-Encoder (ms-marco-MiniLM-L-6-v2). - Database & Infrastructure: PostgreSQL 16, Docker Compose, Ollama Local Server (running
mistral).
phoenix/
├── backend/ # Spring Boot: Security filters, project namespaces, document ingestion tasks
├── ai-engine/ # FastAPI: Embedding pipelines, WLC fusions, fallback orchestrators
├── frontend/ # React SPA: Workspace UI stores, timeline renders, citation matrices
└── Docs/ # Production-grade engineering docs and living knowledge wiki
- Docker & Docker Compose
- Java JDK 21
- Node.js 18+ (npm)
- Python 3.11+
- Ollama Local Server (running
mistralmodel)
docker compose up -dcd ai-engine
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Unix/macOS
pip install -r requirements.txt
python -m uvicorn app.main:app --port 8000 --reloadcd backend
mvn clean install
mvn spring-boot:runcd frontend
npm install
npm run devOpen http://localhost:5173 in your browser.
All core architecture, database schemas, and engineering specifications are kept in the /Docs directory:
| Document Category | Target Specification | Reference File Link |
|---|---|---|
| Product Planning | Core requirements, target personas, and scope bounds. | PRD.md |
| System Features | Functional API, AI, and client specifications. | Feature_List.md |
| Infrastructure Stack | Software dependencies and versions matrix. | Tech_Stack.md |
| Execution Flow | Sequence lifecycles and fallback diagrams. | App_Flow.md |
| Visual Design | Color tokens, panel layouts, and CSS classes. | Design.md |
| Core RAG Logic | Mathematical fusions and state orchestrations. | RAG_Architecture.md |
| API Contract | Gateway REST specifications and payload DTO shapes. | API_Specification.md |
| Data Schema | Shared PostgreSQL and pgvector ERD models. | DB_Schema.md |
| Security Framework | Cryptography, filters, and attack mitigations. | Security.md |
| Dependency Strategy | Ollama, embeddings, and database providers configurations. | Provider_Strategy.md |
| Future Streaming | Planned STOMP WebSocket interface specifications. | WebSocket_Architecture.md |
| Exceptions & Resiliency | Global handlers, timeouts, and JSON error structures. | Error_Handling.md |
| Testing Strategy | Integration validation and hit-rate benchmarking. | Testing_Strategy.md |
| Knowledge Wiki | Consolidated design decisions and guides. | Engineering_Knowledge_Base.md |
| Release Management | Release notes, milestones, and system limitations. | Release_Notes.md |
This project is licensed under the MIT License - see the LICENSE file for details.