Landscape Alliance Knowledge Base AI Assistant
acAIcia is a robust, highly modular AI application designed to securely aggregate, chunk, encode, and intelligently query vast internal research documents natively focusing on agricultural, forestry, soil, and climate-change contexts.
Built using a highly decoupled architecture spanning a Vite + React 18 SPA Frontend (hosted on Railway), a Railway FastAPI Multi-Agent Backend (Mistral inference), and Supabase (pgvector & RRF), it features persistent multi-session chat history, guest query limits (20 max), hybrid search RRF, context-guarded semantic caching, in-chat response feedback, custom research instructions, granular latency telemetry, and an automated RAG evaluation suite.
We maintain comprehensive technical documentation for all major components in AGENTS.md and the docs/ directory:
- AGENTS.md System & Agent Architecture Guide — Master guide for system architecture, agents, API contracts, and developer guidelines.
- System Architecture — High-level infrastructure, semantic caching, hybrid RRF, and session flow.
- Multi-Agent Backend Engine — Pipeline sequence, Guardian/Architect/Synthesis agent prompts, and fallback logic.
- GPU Data Ingestion Pipeline — Parsing PDFs/DOCXs natively via cloud T4 GPUs into
pgvectortensors. - Database Schema (Supabase) — Relational document catalog, user profiles, feedback, cache, chunk logs, and
match_documents_hybridRPC. - Frontend & Feature Guides — Guides for React SPA components, Multi-Session History, Settings (
/settings), In-Chat Feedback (👍/👎), and Admin Observability (/admin). - Architectural Decision Records (ADRs) — Record of architectural decisions (Design system redesign, machine UUID tracking, admin model governance).
- Deployment & Setup Guide — Step-by-step instructions for deploying the backend and frontend to Railway (legacy Modal notes included).
- Expected Costs & Scaling Plan — Data-backed cost model and optimum architecture changes for 10 → 500 users.
- Migration Runbook — Modal → Railway migration details and rollback steps.
- Product Backlog & Engineering Roadmap — Prioritized implementation backlog (P0 hotfixes to P3 hardening) and architecture evolution.
-
Install Frontend Dependencies:
cd frontend && npm install
-
Run React Frontend Locally:
npm run dev
-
Deploy Backend to Railway:
railway up --service "acAIcia Backend" --environment production -
Deploy Frontend to Railway:
railway up --service "acAIcia" --environment production # Or push to main branch for automated Railway build & deployment git push origin main