Spaces:
Running
Running
File size: 5,761 Bytes
f689c7d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | # TaskPilot Architecture Status
**Last Updated:** September 2026
**Active Branch:** `refactor`
**Monolith Status:** Modular Monolith (ADR-001 Compliant)
---
## 1. Architectural Overview
TaskPilot operates as a single-process Spring Boot modular monolith.
- **Cross-module Boundary:** Domain access is mediated strictly by ports and DTOs in `taskpilot-contracts`.
- **AI Module Independence:** `taskpilot-ai` manages its own internal persistence (`ai_logs`, `chat_sessions`, `chat_messages`, `documents`, `document_chunks`) and never directly imports domain entities from `taskpilot-projects` or `taskpilot-users`.
- **Infrastructure Footprint:** Zero microservices, zero Kafka/RabbitMQ brokers, zero distributed cache/lock complexity. Tool execution and agent workflows run entirely in-process.
---
## 2. Stable Boundaries
| Boundary | State | Description |
| :--- | :--- | :--- |
| `taskpilot-contracts` | **Stable** | Standardized SPI layer for all domain operations. |
| `com.taskpilot.ai.rag.*` | **Stable (DONE)** | Complete pgvector, document ingestion, rate-limited embedding gateway, lease fencing, and tenant-isolated retrieval. |
| `com.taskpilot.ai.tools.domain.*` | **Stable** | Domain-specific tool clusters (`ProjectAiTools`, `TaskAiTools`, `SprintAiTools`, `AhpAssignmentAiTools`, `NotificationAiTools`, `SkillAiTools`, `CommentAiTools`, `SystemAiTools`). |
| `com.taskpilot.ai.service.PendingAiActionService` | **Stable** | In-memory human-in-the-loop action coordination. |
---
## 3. Known Hotspots
| Component | Nature | Maintenance Policy |
| :--- | :--- | :--- |
| `StreamingChatEngine` | SSE multi-turn lifecycle orchestrator | Protected. Do NOT add new responsibilities. Only bug fixes and compatibility updates permitted. |
| `SmartRoutingService` | LLM model selection and fallback waterfall | Protected. Routes between primary and fallback models. Speculative provider framework deferred. |
| `ToolCallingRegistryService` | Central tool registration & reflection cache | Protected. Central tool index. Decomposition deferred until tool competition trigger is met. |
---
## 4. Current Model & Provider State
Following the September 2026 model catalog cleanup and targeted correction pass:
| Role | Active Provider | Model Identifier | Status |
| :--- | :--- | :--- | :--- |
| **Primary Streaming & Reasoning** | Gemini | `gemini-3.5-flash` / `gemini-2.5-flash` / `gemini-2.5-pro` | Operational |
| **Groq Reasoning & Communicator** | Groq | `openai/gpt-oss-120b` | Operational |
| **Groq Gatekeeper** | Groq | `openai/gpt-oss-20b` | Operational |
| **Embeddings** | Gemini | `gemini-embedding-2` (768-dim) | Operational |
| **GitHub Models (`models.inference.ai.azure.com`)** | GitHub | Decommissioned | **REMOVED** (HTTP 410 Gone) |
| **Groq Retired Model (`llama-3.3-70b-versatile`)** | Groq | Retired | **REMOVED** (HTTP 404 Not Found) |
| **Groq Deprecated (`llama-4-scout`, `llama-3.1-8b`)** | Groq | Deprecated (Jul/Aug 2026) | **REMOVED** (Replaced by `gpt-oss-120b` & `gpt-oss-20b`) |
| **Gemini Retired (`gemini-2.0-flash/-lite`, `gemini-1.5-pro`)** | Gemini | Deprecated / Shut Down (Jun 2026) | **REMOVED** (Replaced by active 3.x/2.5 series) |
---
## 5. Completed P0 Fixes (September 2026)
- [x] **SQL Backdoor Removal:** Removed `executeQuerySql` from `SystemAiTools`, `TaskPilotAiTools`, and `ToolCallingRegistryService`.
- [x] **AHP Heuristic Decoupling:** Decoupled candidate scoring from LLM availability in `AutoAssignmentService`. Configurable 5000ms bounded timeout (`ai.assignment.explanation-timeout-ms:5000`) and deterministic local fallback. Truthful model telemetry recording.
- [x] **Model Catalog Cleanup:** Purged defunct GitHub inference endpoints, dead Gemini 2.0 endpoints, and retired Groq models (`llama-3.3-70b-versatile`, `meta-llama/llama-4-scout-17b-16e-instruct`, `llama-3.1-8b-instant`). Replaced hardcoded references with dynamic routing.
- [x] **Fake Adapter Isolation:** Moved `com.taskpilot.ai.adapter.fake.*` to `src/test/java`. Production package is clean.
- [x] **Full Regression Verification:** 148 tests executed, 141 passed, 0 failures, 0 errors, 7 skipped in `taskpilot-ai`.
---
## 6. Deferred Refactors & Trigger Conditions
| Candidate Refactor | Current Decision | Concrete Trigger Condition |
| :--- | :--- | :--- |
| **`StreamingChatEngine` Decomposition** | Deferred | Triggered when SSE protocol and tool lifecycle require simultaneous conflicting changes for a new streaming protocol. |
| **Provider Plugin Architecture** | Deferred | Triggered when more than 3 active inference providers require distinct dynamic runtime credential rotation. |
| **`ToolCallingRegistryService` Splitting** | Deferred | Triggered when tool groups require distinct security scopes or compete over execution interceptors. |
| **Durable `PendingAiActionService`** | Deferred | Triggered when deploying multi-instance TaskPilot behind a load balancer requiring cross-JVM action confirmation. |
---
## 7. Reusable Agent Intelligence & Knowledge Consolidation (September 2026)
- **Canonical Knowledge Root:** Consolidated all reusable engineering skills, agent instructions, prompts, and playbooks under `taskpilot/.agents/`.
- **Duplicate Reconciliation:** Reconciled duplicate `.agent` (singular) and `.agents` (plural) copies. Purged obsolete machine-local `.agent` directories.
- **Canonical Architecture Skill:** Established single canonical copy of generic architecture maintenance workflows at `.agents/skills/taskpilot-architecture-maintenance/SKILL.md`.
- **Context7 & Catalog Portability:** Imported `context7` library documentation skill into canonical `.agents/skills/context7/`. Created `.agents/README.md` defining discovery protocols and zero-duplicate rules.
|