NexusCore Architecture (Canonical Design)

Canonical Architecture Document: This is the detailed architectural design of NexusCore. For the Gate/SSOT entrypoint, see docs/ARCHITECTURE.md.

System Overview

NexusCore is a multi-agent AI development framework with integrated quality gates, LLM routing, and constitutional governance.

High-Level Architecture

graph TB
    User[User/Developer] --> Orchestrator[Orchestrator]

    Orchestrator --> AgentLayer[Agent Layer]
    AgentLayer --> LLMRouter[LLM Router]
    AgentLayer --> QualityGates[Quality Gates]

    subgraph "Agent Layer"
        ArchitectAgent[Architect Agent]
        CoderAgent[Coder Agent]
        DebuggerAgent[Debugger Agent]
        TesterAgent[Tester Agent]
        GuardianAgent[Guardian Agent]
        RequirementAgent[Requirement Agent]
        PostmortemAgent[Postmortem Agent]
        KnowledgeAgent[Knowledge Curator]
        PolicyAgent[Policy Agent]
        CouncilAgent[Constitutional Council]
    end

    subgraph "LLM Router"
        TaskRouter[Task-based Routing]
        ModelPool[Model Pool]
        BudgetManager[Budget Manager]
    end

    subgraph "Quality Gates"
        Tier1[Tier 1: Code Quality]
        Tier2[Tier 2: Mutation Testing]
    end

    ModelPool --> GLM[GLM (Zhipu AI)]
    ModelPool --> MiniMax[MiniMax]

    Tier1 --> Coverage[Coverage Analysis]
    Tier1 --> Pylint[Pylint]
    Tier1 --> Mypy[Type Checking]
    Tier1 --> Bandit[Security Scan]

    Tier2 --> MutationTest[Mutation Testing]

    GuardianAgent --> QualityGates
    CouncilAgent --> PolicyStore[Policy Store]

Component Details

1. Agent Layer

Core Agents

ArchitectAgent (src/nexuscore/agents/architect_agent.py)

Designs project structure
Creates architectural plans
Technology stack recommendations

CoderAgent (src/nexuscore/agents/coder_agent.py)

Implements code based on requirements
Syntax validation
Self-healing code generation

DebuggerAgent (src/nexuscore/agents/debugger_agent.py)

Analyzes error logs
Generates fixes
Creates unified diffs
Knowledge base integration

TesterAgent (src/nexuscore/agents/tester_agent.py)

Generates test cases
Context-aware testing
Integration with test strategy

GuardianAgent (src/nexuscore/agents/guardian_agent.py)

Multi-tier quality gates
Code review automation
Approval/rejection workflow
Git integration

Support Agents

RequirementAgent (src/nexuscore/agents/requirement_agent.py)

Requirement elicitation
Specification analysis
Clarity checking

PostmortemAgent (src/nexuscore/agents/postmortem_agent.py)

Failure analysis
Root cause identification
Recommendation generation

KnowledgeCuratorAgent (src/nexuscore/agents/knowledge_curator_agent.py)

Knowledge base management
Experience capture
Pattern extraction

PolicyAgent (src/nexuscore/agents/policy_agent.py)

Policy enforcement
Compliance checking
Rule validation

ConstitutionalCouncilAgent (src/nexuscore/agents/constitutional_council_agent.py)

Policy amendment management
Constitutional governance
Amendment approval workflow

2. LLM Router

Task-Based Routing (src/nexuscore/llm/llm_router.py)

Routes tasks to optimal LLM based on:

Task type (code_generate, code_review, debug, etc.)
Cost constraints
Model capabilities
Fallback strategies

Supported Task Types:

{
    'code_generate': 'glm:glm-4-plus',
    'code_review': 'glm:glm-4-plus',
    'debug': 'glm:glm-4-plus',
    'test_generate': 'glm:glm-4-plus',
    'architect': 'glm:glm-4-plus',
    'policy_check': 'glm:glm-4-plus',
    'postmortem_analyze': 'glm:glm-4-plus',
    'knowledge_curate': 'minimax:minimax-m2.7',
    # ... and more
}

Budget Management:

Daily spending limits
Cost tracking per task
Automatic model downgrading

3. Quality Gates

Tier 1: Code Quality

Coverage Analysis (src/nexuscore/utils/code_analyzer.py)

Line coverage measurement
Branch coverage
Threshold enforcement (default: 80%)

Static Analysis:

Pylint: Code quality score (threshold: 8.0/10)
Mypy: Type checking
Bandit: Security vulnerability detection

Output: QualityReport dataclass

@dataclass
class QualityReport:
    passed: bool
    coverage_percentage: float
    coverage_passed: bool
    pylint_score: float
    pylint_passed: bool
    mypy_passed: bool
    mypy_output: str
    bandit_passed: bool
    security_issues: List[SecurityIssue]
    feedback: str
    violations: List[str]

Tier 2: Mutation Testing

MutationTesterAgent (src/nexuscore/agents/mutation_tester_agent.py)

Generates code mutants
Runs test suite against mutations
Calculates mutation score
Identifies weak tests

Output: MutationReport dataclass

@dataclass
class MutationReport:
    passed: bool
    mutation_score: float
    total_mutants: int
    killed: int
    survived: int
    timeout: int
    suspicious: int
    survived_mutants: List[Mutant]

4. Policy & Governance

PolicyInterface (src/nexuscore/agents/policy_interface.py)

User-facing policy configuration
Gradio UI integration
Safe defaults

ConstitutionalCouncilAgent

Amendment proposal system
Policy validation
Approval workflow
Audit trail

5. Context & Analysis

ContextAgent (src/nexuscore/agents/context_agent.py)

Project context gathering
Framework detection
Error prevention rules

ContextAnalyzer (src/nexuscore/agents/context_analyzer.py)

Tech stack detection
Dependency analysis
Environment detection
File structure scanning

Data Flow

Typical Development Workflow

sequenceDiagram
    participant User
    participant Orchestrator
    participant RequirementAgent
    participant ArchitectAgent
    participant CoderAgent
    participant GuardianAgent
    participant LLMRouter

    User->>Orchestrator: Submit requirement
    Orchestrator->>RequirementAgent: Analyze requirement
    RequirementAgent->>LLMRouter: Execute LLM task (requirement)
    LLMRouter-->>RequirementAgent: Structured requirement
    RequirementAgent-->>Orchestrator: Analyzed requirement

    Orchestrator->>ArchitectAgent: Design structure
    ArchitectAgent->>LLMRouter: Execute LLM task (arch_design)
    LLMRouter-->>ArchitectAgent: Project structure
    ArchitectAgent-->>Orchestrator: Design document

    Orchestrator->>CoderAgent: Implement code
    CoderAgent->>LLMRouter: Execute LLM task (code_generate)
    LLMRouter-->>CoderAgent: Generated code
    CoderAgent-->>Orchestrator: Implementation

    Orchestrator->>GuardianAgent: Review code
    GuardianAgent->>GuardianAgent: Run Tier 1 Quality Gates
    GuardianAgent->>GuardianAgent: Run Tier 2 Mutation Tests
    GuardianAgent-->>Orchestrator: Approval/Rejection

    Orchestrator-->>User: Final result

Guardian Review Flow

graph LR
    Code[Code Changes] --> Guardian[Guardian Agent]
    Guardian --> Tier1[Tier 1 Gates]

    Tier1 --> Coverage{Coverage >= 80%?}
    Tier1 --> Pylint{Pylint >= 8.0?}
    Tier1 --> Mypy{Mypy Pass?}
    Tier1 --> Bandit{No Security Issues?}

    Coverage -->|Yes| Tier1Pass[Tier 1 Pass]
    Pylint -->|Yes| Tier1Pass
    Mypy -->|Yes| Tier1Pass
    Bandit -->|Yes| Tier1Pass

    Coverage -->|No| Tier1Fail[Tier 1 Fail]
    Pylint -->|No| Tier1Fail
    Mypy -->|No| Tier1Fail
    Bandit -->|No| Tier1Fail

    Tier1Pass --> Tier2[Tier 2: Mutation Testing]
    Tier2 --> MutationScore{Mutation Score >= 70%?}

    MutationScore -->|Yes| Approved[✅ Approved]
    MutationScore -->|No| Rejected[❌ Rejected]
    Tier1Fail --> Rejected

File Structure

src/nexuscore/
├── agents/                    # AI Agent implementations
│   ├── base_agent.py          # Base agent class with LLM integration
│   ├── architect_agent.py     # Architecture design
│   ├── coder_agent.py         # Code generation
│   ├── debugger_agent.py      # Error fixing
│   ├── tester_agent.py        # Test generation
│   ├── guardian_agent.py      # Quality gates
│   ├── requirement_agent.py   # Requirement analysis
│   ├── postmortem_agent.py    # Failure analysis
│   ├── knowledge_curator_agent.py  # Knowledge management
│   ├── policy_agent.py        # Policy enforcement
│   ├── constitutional_council_agent.py  # Governance
│   └── mutation_tester_agent.py  # Mutation testing
│
├── llm/                       # LLM integration layer
│   ├── llm_router.py          # Task-based model routing
│   ├── budget_manager.py      # Cost tracking
│   └── providers/             # LLM provider implementations
│
├── utils/                     # Utility modules
│   ├── code_analyzer.py       # Code quality analysis
│   ├── vcs.py                 # Git operations
│   ├── diff_tools.py          # Diff generation
│   └── test_generator.py     # Test generation utilities
│
└── webapp/                    # SaaS管理UI（Flask HTML画面）
    ├── auth.py                # GitHub OAuth認証（Flask Blueprint、旧版）
    ├── views_dashboard.py     # ダッシュボード画面
    ├── views_projects.py      # プロジェクト管理画面
    ├── views_logs.py          # ログ閲覧画面
    └── models.py              # SQLAlchemyモデル

Web層アーキテクチャ（Flask / FastAPI 責務分離）

NexusCoreは2つのWebフレームワークを用途に応じて使い分けます:

層	フレームワーク	パス	役割	移行対象
公開API	FastAPI	`/api/v1/*`	外部統合向けJSON API	—
OAuth認証	FastAPI	`/api/v1/auth/*`	GitHub OAuth認証	完了
統合UI	Gradio	`:7860`	コード生成→テスト→履歴フロー	—
管理UI	Flask	`/projects/`, `/dashboard/`, `/logs/*`	ブラウザ向けHTML画面	対象外

Flask管理UIがFastAPI移行対象外の理由:

レスポンスが全てインラインHTML — JSON APIはFastAPI（api/routes/）が既に提供済み
データアクセスがDB直叩き — SQLAlchemyで直接クエリ。API層を経由しない
責務分離の設計意図 — Flask = 人間向けブラウザUI、FastAPI = 機械向けJSON API
コード内に明記済み — 各viewsファイルに「FastAPI API migrationの対象外」とコメントあり

Key Design Patterns

1. Agent Pattern

Each agent inherits from BaseAgent
Standardized LLM interaction via execute_llm_task()
Task-specific prompts via system_prompt

2. Quality Gate Pattern

Multi-tier validation (Tier 1: Static, Tier 2: Dynamic)
Fail-fast on critical issues
Detailed feedback for failures

3. Constitutional AI Pattern

Policy-driven decision making
Amendment proposal system
Audit trail for governance

4. Router Pattern

Task-based model selection
Cost optimization
Automatic fallback

5. Knowledge Base Pattern

Experience capture from failures
Pattern matching for solutions
Global/local knowledge bases

Technology Stack

Languages:

Python 3.11+

AI/LLM:

GLM (Zhipu AI) (GLM-4-Plus, GLM-4-Flash)
MiniMax (MiniMax-M2.7)

Testing:

pytest
pytest-cov
mutation testing (custom)

Code Quality:

pylint
mypy
bandit

Version Control:

GitPython

Web Framework:

FastAPI (public API: /api/v1/*, OAuth: /api/v1/auth/*)
Flask (SaaS管理UI: /projects/*, /dashboard/*, /logs/*)
Gradio (統合UI)

Other:

patch-ng (unified diff parsing)
dataclasses (structured data)

Scalability & Performance

Current State:

Synchronous agent execution
Single-process architecture
In-memory state management

Future Considerations:

Parallel agent execution
Distributed task queue (Celery ready)
Persistent state storage
Horizontal scaling via API layer

Security

Current Measures:

Bandit security scanning
API key management
Budget limits
Policy enforcement

Sandboxing:

Code execution in isolated environment
File system access controls
Network restrictions

Monitoring & Observability

Logging:

Structured logging via Python logging
Agent-level tracing
LLM call tracking

Metrics:

Budget tracking per task
Quality gate pass/fail rates
Agent execution times
LLM token usage

Extension Points

New Agents: Inherit from BaseAgent, implement task-specific logic
New LLM Providers: Implement provider interface in llm/providers/
Custom Quality Gates: Extend GuardianAgent with new validators
Policy Rules: Add to ConstitutionalCouncilAgent policy store
Knowledge Patterns: Extend knowledge base with custom matchers