Conclave is an enterprise-grade multi-agent collaboration workspace designed to unify conversation context across fragmented local Large Language Models (LLM) run via Ollama.
The platform serves as a systems engineering portfolio showcasing advanced Java/Spring Boot orchestration patterns, real-time WebSocket communication, thread-safe pessimistic locking, and reactive state management.
- Beyond an API Call
- Beyond the Black Box
- Real-Time, Evolved
- Local Intelligence
- Building Agents Twice
- Why One Backend Isn't Enough
- ENGINEERING JOURNEY
The generative AI landscape is highly siloed. Power users frequently "tab-hop" between different model interfaces to leverage their unique strengths (e.g., Llama 3 for coding, Mistral for creative writing, Gemma for structured logical tasks). This workflow introduces Context Fragmentation: users must manually copy-paste background information, goals, and previous outputs between tabs to maintain a coherent thread. This results in:
- Context Tax: High cognitive load and wasted time manually syncing state across multiple windows.
- Information Decay: Loss of details, nuances, and conversational history during copy-pasting.
- Token Inefficiency: Redundant transcript uploads that bloat local context windows and system memory.
Conclave provides a unified "meeting room" where multiple models participate as distinct agents in a single, moderated thread. Rather than binding database schemas to one vendor, Conclave stores all turns in a provider-agnostic Canonical Schema (CanonicalMessage).
Outgoing history is dynamically mapped to the target vendor's API format at runtime, and incoming responses are normalized back. All models share the same "memory" and objective state automatically, eliminating manual copy-pasting.
Here is the step-by-step visual workflow of the Conclave Console, from authentication to room configuration:
| 🔐 Login & Authentication Portal | 🛠️ Room Configuration Wizard |
|---|---|
 |
 |
Below is the actual visual verification of a completed E2E multi-agent execution run. It shows a user prompt triggering a sequential chain of local LLM responses from Llama 3 (Lead-Writer) and Mistral (Code-Critic) streaming in real-time over WebSockets:
Below is a mockup of the Conclave Console, showcasing the multi-agent room layout with color-coded message bubbles and the pause control desk:
The following diagram maps the high-level system topology, protocol boundaries, and integration flows of Conclave. It details how the React client interacts with the Spring Boot service and local Ollama daemon:
graph TB
subgraph "Client Panel (React 19)"
UI[Console Client UI]
Zustand[(Zustand State Store)]
end
subgraph "Transport Gateway"
REST[REST API - Port 8080]
WS[WebSocket STOMP Channel]
end
subgraph "Orchestration Core (Spring Boot)"
Security[Stateless JWT Filter]
Interceptor[STOMP Upgrade Interceptor]
Orch[MessageOrchestratorImpl]
Pipeline[PipelineManagerImpl]
Janitor[WorkflowStateServiceImpl]
Registry[ModelRegistryImpl]
end
subgraph "Infrastructure Tier"
DB[(PostgreSQL 16 Database)]
Ollama[Ollama Server - Port 11434]
end
%% Network flows
UI -->|HTTPS Requests| REST
UI -->|STOMP subscriptions| WS
REST --> Security
WS --> Interceptor
Security --> Orch
Interceptor --> Orch
Orch -->|Dynamic Bean Resolution| Registry
Orch -->|Acquire Lock| DB
Orch -->|Context Compression| Janitor
Registry -->|Local Inference| Ollama
Orch -->|Push chunks chunk-by-chunk| WS
WS -->|CONTENT_CHUNK| Zustand
Zustand -->|Re-render UI Nodes| UI
- Multi-Model Schema Translation: Out-of-the-box translation mapping canonical history records to Llama 3 special tokens, Mistral INST format, and Gemma control token structures.
- Dynamic Registry Resolution: A custom
@Serviceregistry resolving Spring AI client beans dynamically at runtime based on assigned roles. - Real-time WebSocket Streaming: Standardized STOMP protocol channels pushing model "typing" states (
TURN_STARTED), word-by-word streaming deltas (CONTENT_CHUNK), and completion usage metrics (TURN_COMPLETED) to clients. - Pause & Intervene (Pessimistic Locking): Database-level locks (
SELECT FOR UPDATE) halting active sequential queues instantly when a pause is triggered, allowing users to inject manual corrections (isIntervention = true) before resuming the pipeline. - Context Janitor (Auto-Compression): Automatically triggers when message logs exceed 10. Invokes Llama 3 to compress history into a structured
WorkflowState(draft and comments) and purges middle database rows, cutting token costs by up to 75%.
| Layer | Selected Tech | Version | Rationale |
|---|---|---|---|
| Backend | Spring Boot | 3.3.1 |
Solid baseline for Dependency Injection, security filters, and transaction scopes. |
| Concurrency | Java (JDK) | 21 |
Utilizes Virtual Threads (Project Loom) to handle slow blocking LLM calls at scale without exhausting thread pools. |
| AI Integration | Spring AI | 1.0.0-M1 |
Standardizes chat client interfaces across local models using Ollama. |
| Database | PostgreSQL | 16 |
Relational consistency. Enforces pessimistic write locks (SELECT FOR UPDATE) for pipeline safety. |
| Realtime Gateway | WebSockets (STOMP) | Spring Message |
Multiplexed subscription routing and custom headers for real-time events. |
| Frontend | React | 19 |
High-performance rendering loops during real-time streams. |
| State Store | Zustand | latest |
Decouples WebSocket stream callbacks from React re-render paths. |
| Styling | Tailwind CSS | latest |
High-density grid alignments, HSL color elevations (Level 0-3), and autofill overrides. |
Conclave/
├── docker-compose.yml # Provisions PostgreSQL 16 local instance
├── README.md # This file (Repository Landing Page)
├── Docs/ # Architectural Specifications & Index
│ ├── README.md # Documentation Index & Navigation Portal
│ ├── PRD.md # Vision, requirements, and scope limits
│ ├── System_Architecture.md # Class diagrams, JPA mappings, execution flow
│ ├── DB_Schema.md # ER diagrams, pessimistic locking, index designs
│ ├── API_Specification.md # Endpoint specs, WebSocket STOMP payload schemas
│ ├── Security.md # JWT details, WebSocket auth interceptor flow
│ ├── Error_Handling_Strategy.md # Global Exception Handler and recovery flow
│ ├── WebSocket_Architecture.md # Message routing and fallback retry strategies
│ ├── Testing_Strategy.md # Validation matrix across all project tiers
│ ├── UI_Design.md # Front-end layout structures and color guides
│ ├── Model_Adapter_Strategy.md # Prompt token mapping strategies
│ ├── Portfolio_And_Interview_Readiness_Defense.md # System design highlights and FAQs
│ ├── Release_Notes_v1.0.0.md # Version 1.0.0 release log
│ ├── Learning/ # Onboarding Engineering Handbook
│ │ ├── README.md # Handbook Index / Table of Contents
│ │ └── 01_Developer_Environment_Setup.md ... 09_Tailwind_Customization_For_Tactical_UIs.md
│ └── Roadmap/ # Implementation Phases
│ ├── README.md # Roadmap Index & Development Workflow
│ └── Phase_01_Project_Setup.md ... Phase_12_Documentation_And_Repository_Audit.md
├── backend/ # Spring Boot Java Application
│ ├── README.md # Backend Deep Dive & Service Specifications
│ ├── pom.xml # Maven dependency configuration
│ └── src/main/java/com/conclave/ # Java codebase
│ ├── BackendApplication.java # Main entrance class
│ ├── config/ # Configuration (Async, Security, WebSocket)
│ ├── controller/ # REST controllers (Auth, Room, Chat)
│ ├── domain/ # Canonical DTOs and JPA Entities
│ ├── exception/ # Exception handling structures
│ ├── integration/ # Adapters (Llama/Mistral/Gemma) & Registry
│ ├── repository/ # Spring Data JPA repositories
│ ├── security/ # Security filters and token providers
│ ├── service/ # Message orchestration and pipeline locks
│ └── util/ # Parsing and validation utilities
└── frontend/ # React Single Page Client
├── README.md # Frontend Deep Dive & Component Structure
├── package.json # NPM script registry and dependencies
├── tailwind.config.js # Color palette configurations
├── vite.config.js # Dev-server configuration
├── index.html # Root HTML entrance
├── e2e/ # Playwright browser integration tests
└── src/ # React source folder
├── App.css / index.css # Style overrides and design tokens
├── components/ # MessageBubble, ChatBar, Sidebar, etc.
├── services/ # API and WebSocket client adapters
├── store/ # Zustand store managers (auth, room, chat)
├── tests/ # Vitest component unit tests
└── views/ # Page Views (Login, Register, Setup, Room)
For a detailed step-by-step walkthrough, refer to Docs/Learning/01_Developer_Environment_Setup.md.
Provision the local PostgreSQL 16 container:
docker compose up -d- Navigate to the backend folder:
cd backend - Copy the
.env.examplefile in the root folder tobackend/.env(or configure host variables). - Start the application with the
devprofile:The backend server starts on./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
http://localhost:8080.
- Navigate to the frontend folder:
cd ../frontend - Install node modules and start the Vite local server:
Open your browser to
npm install npm run dev
http://localhost:5173.
To run local models:
- Install Ollama on your machine.
- Pull the required models:
ollama pull llama3 ollama pull mistral ollama pull gemma
- Verify Ollama is running locally on port
11434(curl http://localhost:11434).
- User Message Submission: The user submits a prompt mentioning models (e.g. "@llama3 write a function, @mistral review it").
- Context Resolution: The backend receives the message, parses the mentions, and locks the room using a pessimistic database lock to enforce transaction isolation.
- Pipeline Sequential Loop: The backend iterates through the mentioned models sequentially.
- Adapter Translation: Before invoking the model via Ollama, the message history is translated into the model's native format.
- Streaming Output: Model responses are streamed back chunk-by-chunk via the WebSockets STOMP broker directly updating the React Zustand store.
- Compression (Janitor): If the history length exceeds 10 messages, the
WorkflowStateServiceImplruns a compression pass to keep token size low and purges older DB messages. - Pause/Resume: The user can pause execution mid-pipeline, insert an intervention, and resume, updating the database state immediately.
The repository includes test suites spanning the entire development lifecycle:
- Backend Unit & Integration Tests: Run
mvn testin thebackend/directory to run adapter schema validations, dynamic registry mappings, and concurrency lock thread tests. - Frontend Unit Tests: Run
npm run testinsidefrontend/to run component-level tests. - Playwright E2E Integration Tests: Run
npm run test:e2einsidefrontend/to spin up a mock-driven user session, validating page navigation and room setup workflows.
For the full testing strategy, review Docs/Testing_Strategy.md.
Use the table below to navigate to the core documentation modules:
| Document | Direct Link | Purpose |
|---|---|---|
| Documentation Portal | Docs/README.md | Entry point to all specifications, diagrams, and audits. |
| Product Requirements | Docs/PRD.md | Vision, target audience, features list, and constraints. |
| System Architecture | Docs/System_Architecture.md | High-level system structure, database design, and sequence diagrams. |
| Database Schema | Docs/DB_Schema.md | Entity relationships, pessimistic lock descriptions, and indices. |
| Security Architecture | Docs/Security.md | Stateless JWT security, WebSocket handshake, and endpoint authority. |
| Engineering Handbook | Docs/Learning/README.md | 9-chapter onboarding curriculum covering specific backend/frontend implementations. |
| Implementation Roadmap | Docs/Roadmap/README.md | 12 atomic phases and milestones for building Conclave. |
- Vector RAG Integration (v2.0.0): Document uploads and automatic vector chunking to inject relevant context during LLM inference.
- Billing Engine (v2.0.0): Support Stripe billing integrated with audited token usage logs.
- Parallel Consensus (v3.0.0): Query multiple models simultaneously and generate a combined evaluation via a critic model.
Contributions are welcome. Please ensure that:
- All Maven tests pass (
mvn test). - Frontend lint checks pass (
npm run lint). - You follow the Git branch name policy defined in Docs/Roadmap/README.md.
- Spring Boot & Spring AI teams for simplifying local model clients.
- Ollama project for enabling lightweight local model inference.
This project is licensed under the MIT License - see the LICENSE file for details.