taskpilot / docs /ARCHITECTURE_STATUS.md
github-actions[bot]
Sync repository to Hugging Face Space
f689c7d
|
Raw History Blame Contribute Delete
5.76 kB

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)

  • SQL Backdoor Removal: Removed executeQuerySql from SystemAiTools, TaskPilotAiTools, and ToolCallingRegistryService.
  • 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.
  • 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.
  • Fake Adapter Isolation: Moved com.taskpilot.ai.adapter.fake.* to src/test/java. Production package is clean.
  • 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.