Kiến trúc hệ thống

Tổng quan

Galaxy CLI được xây dựng theo kiến trúc Orchestrator + Specialized Agents + Tools, tối ưu hóa cho feature-driven development.

┌─────────────────────────────────────────────┐
│         Galaxy CLI (Ink React App)          │
│  - User Input với autocomplete              │
│  - Spinner loading states                   │
│  - Figlet banner                            │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│      Gemini 2.5 Flash (Orchestrator)        │
│  - Tool calling & function execution        │
│  - Plan execution & todos display           │
│  - Multi-language support (EN/VI)           │
└─────────────────┬───────────────────────────┘
                  │
        ┌─────────┴─────────────┐
        │                       │
        ▼                       ▼
┌───────────────┐       ┌──────────────────┐
│  BA Analyzer  │       │ Planning Agent   │
│ gpt-oss:120b  │       │ qwen3-coder:480b │
│               │       │ Feature-driven   │
└───────────────┘       └──────────────────┘
        │                       │
        │                       ▼
        │               ┌──────────────────────┐
        │               │ Execution Plan       │
        │               │ - Feature steps      │
        │               │ - Tool selection     │
        │               └──────────────────────┘
        │                       │
        └───────────┬───────────┘
                    ▼
        ┌───────────────────────────┐
        │   Code Generate Agent     │
        │   qwen3-coder:480b-cloud  │
        │                           │
        │ ┌─────────────────────┐   │
        │ │ Integrated Tools:   │   │
        │ │ - file_write        │   │
        │ │ - file_read         │   │
        │ │ - command_run       │   │
        │ │ - file_search       │   │
        │ └─────────────────────┘   │
        │                           │
        │ Output: {step, status,    │
        │  message, filesCreated}   │
        └───────────────────────────┘
                    │
                    ▼
        ┌───────────────────────────┐
        │  Tool Registry (28 tools) │
        │                           │
        │  📁 File   🔧 Command     │
        │  🔀 Git    📝 Document    │
        │  🧪 Test   🔍 Search      │
        └───────────────────────────┘

Các thành phần chính

1. Ink React App (Frontend CLI)

Công nghệ:

• Ink - React for terminal
• TypeScript - Type safety
• Figlet - ASCII art banner
• ink-spinner - Loading animations

Nhiệm vụ:

• Render UI trong terminal
• Xử lý user input với autocomplete
• Hiển thị loading states
• Show todos progress (☐/☒)
• Format tool outputs

File chính:

• source/app.tsx - Main Ink component
• source/cli.tsx - CLI entry point
• source/utils/message-formatters.tsx - Format tool results

Ghi chú

Ink cho phép build CLI app như React web app với components, state management, và hooks.

2. Gemini Orchestrator (Brain)

Model: Google Gemini 2.5 Flash

Nhiệm vụ:

• Điều phối toàn bộ workflow
• Tool calling & function execution
• Quyết định khi nào gọi BA/Planning/Code agents
• Execute plan từ Planning Agent
• Hiển thị todos với ☐/☒
• Multi-language response (EN/VI)

File chính:

• source/ai/orchestrator.ts - Main orchestrator logic
• source/connections/gemini.ts - Gemini API wrapper
• source/prompts/orchestrator.ts - System prompts

Decision Logic:

// Khi nào dùng BA Analyzer?
if (userRequest.includes('tạo dự án') ||
    userRequest.includes('create project') ||
    isComplexFeatureRequest(userRequest)) {
  await tools.ba_it_analyze(userRequest);
}

// Khi nào dùng Planning Agent?
if (userConfirmed && hasBAAnalysis) {
  await tools.plan_task(userContext, baAnalysis);
}

// Khi nào execute plan?
if (hasPlan) {
  for (const step of plan.steps) {
    await executeStep(step);
  }
}

Mẹo

Orchestrator là điểm trung tâm của Galaxy CLI. Mọi quyết định quan trọng đều được thực hiện ở đây.

3. BA Analyzer Agent

Model: gpt-oss:120b-cloud (Ollama)

Nhiệm vụ:

• Phân tích yêu cầu người dùng
• Xác định project type: create_project vs update_project
• Đề xuất tech stack
• Define core features
• Create data models
• Suggest API endpoints
• Output: English only (internal consistency)

Input:

{
  userRequest: string,
  currentContext: ProjectContext
}

Output:

{
  projectName: string,
  type: 'create_project' | 'update_project',
  description: string,
  coreFeatures: Feature[],
  technicalStack: TechStack,
  dataModels: DataModel[],
  apiEndpoints: APIEndpoint[],
  estimatedDevelopmentTime: string,
  recommendations: string[],
  questionsForUser: string[]
}

File chính:

• source/tools/ba-it-analyzer.ts - BA tool implementation
• source/prompts/ba-it-analyzer.ts - BA system prompts
• source/connections/ollama.ts - Ollama connection

Ghi chú

BA Agent LUÔN output English để đảm bảo consistency với Planning Agent.

4. Planning Agent

Model: qwen3-coder:480b-cloud (Ollama)

Nhiệm vụ:

• Map coreFeatures → execution steps
• 1 must-have feature = 1 code_generate step
• Add conditional test/review steps (based on CLI flags)
• Chọn tools phù hợp
• Ước lượng thời gian

Input:

{
  userContext: string,
  baAnalysis?: BAAnalysis,
  systemContext: {
    testEnabled: boolean,
    reviewEnabled: boolean
  }
}

Output:

{
  summary: string,
  steps: Step[],
  estimatedTime: 'quick' | 'medium' | 'long'
}

// Step format:
{
  step: number,
  tool: string,
  action: string,
  featureName?: string,
  featureDescription?: string,
  priority?: string,
  reasoning: string
}

Feature-Driven Mapping:

// Example: E-commerce với 3 core features
coreFeatures = [
  { name: 'Product Catalog', priority: 'must-have' },
  { name: 'Shopping Cart', priority: 'must-have' },
  { name: 'Checkout', priority: 'must-have' }
];

// Planning Agent tạo:
steps = [
  { step: 1, tool: 'command_run', action: 'Initialize Next.js' },
  { step: 2, tool: 'install_dependencies' },
  { step: 3, tool: 'code_generate', featureName: 'Product Catalog' },
  { step: 4, tool: 'code_generate', featureName: 'Shopping Cart' },
  { step: 5, tool: 'code_generate', featureName: 'Checkout' },
  // Conditional steps
  { step: 6, tool: 'test_run' },  // if testEnabled
  { step: 7, tool: 'code_review' } // if reviewEnabled
];

File chính:

• source/tools/planning-agent.ts - Planning tool
• source/prompts/planning-agent.ts - Planning prompts

Mẹo

Planning Agent là cầu nối giữa BA analysis và code execution.

5. Code Generate Agent ✨ NEW

Model: qwen3-coder:480b-cloud (Ollama)

Nhiệm vụ:

• Nhận feature spec từ planning step
• Generate production-ready code (NO placeholders!)
• Self-contained execution với integrated tools
• Write files, run commands
• Return execution result

Input:

{
  step: number,
  featureName: string,
  featureDescription: string,
  priority: string,
  technicalStack: TechStack,
  userStories?: string[],
  dataModel?: DataModel[],
  apiEndpoints?: APIEndpoint[]
}

Output:

{
  step: number,
  status: 'done' | 'error',
  message: string,
  filesCreated: string[]
}

Integrated Tools:

• file_write - Write code to files
• file_read - Read existing code
• command_run - Run build/install commands
• file_search - Search codebase

File chính:

• source/tools/code-generate-agent.ts - Code gen tool
• source/connections/ollama.ts - Ollama connection

Ghi chú

Code Generate Agent là self-contained executor. Không cần Orchestrator can thiệp sau khi gọi.

6. Tool Registry

Tổng số: 28+ specialized tools

Phân loại:

📁 File Operations (6 tools)

• file_read - Đọc file
• file_write - Ghi/tạo file
• file_list - List files
• file_search - Search pattern
• file_tree - Hiển thị cây thư mục
• file_delete - Xóa file

🔀 Git Operations (5 tools)

• git_status
• git_commit
• git_push
• git_pull
• git_diff

🔧 Command & Testing (3 tools)

• command_run - Chạy shell commands
• install_dependencies - Auto-detect & install
• test_run - Chạy tests

📝 Document Parsing (1 tool)

• document_parse - Parse PDF/DOCX/XLSX

🧠 AI Analysis & Planning (3 tools)

• ba_it_analyze - BA analysis
• plan_task - Planning
• code_generate - Code generation

File chính:

• source/tools/registry.ts - Tool registration
• source/tools/types.ts - Tool types
• source/tools/file-operations.ts
• source/tools/git-operations.ts
• source/tools/command-runner.ts
• source/tools/document-parser.ts

Design Patterns

1. Orchestrator Pattern

Trước đây (Multi-agent):

• 11 agents riêng biệt
• Phức tạp, khó maintain
• Nhiều context switching
• Agents phải communicate với nhau

Hiện tại (Orchestrator):

• 1 Orchestrator (Gemini)
• 3 Specialized agents (BA, Planning, Code Gen)
• 28 focused tools
• Clear responsibilities
• Dễ debug và maintain

2. Feature-Driven Execution

Thay vì chia nhỏ thành nhiều technical tasks, Galaxy chia theo features:

// ❌ Old way: Technical tasks
[
  'Create components folder',
  'Create Product component',
  'Add styling',
  'Connect to API',
  'Add state management'
]

// ✅ New way: Feature-driven
[
  {
    step: 1,
    tool: 'code_generate',
    featureName: 'Product Catalog',
    // Code Gen Agent tự handle tất cả sub-tasks
  }
]

3. Self-Contained Execution

Code Generate Agent là self-contained:

• Không cần Orchestrator micro-manage
• Tự quyết định files to create
• Tự handle dependencies
• Tự error recovery

Data Flow

Create Project Flow

User Input
  ↓
Orchestrator nhận yêu cầu
  ↓
Gọi ba_it_analyze()
  ↓
BA Agent phân tích → BAAnalysis (EN)
  ↓
Orchestrator present analysis (VI/EN)
  ↓
User xác nhận
  ↓
Gọi plan_task(userContext, baAnalysis)
  ↓
Planning Agent tạo plan → ExecutionPlan
  ↓
Orchestrator present plan với todos
  ↓
Orchestrator execute từng step:
  - command_run: Initialize project
  - install_dependencies
  - code_generate(feature1) → filesCreated[]
  - code_generate(feature2) → filesCreated[]
  - test_run (if enabled)
  - code_review (if enabled)
  ↓
Complete! Show summary

Add Feature Flow

User Input
  ↓
Orchestrator nhận yêu cầu
  ↓
Gọi ba_it_analyze() với type='update_project'
  ↓
BA Agent phân tích feature
  ↓
User xác nhận
  ↓
Gọi plan_task()
  ↓
Planning Agent tạo plan (skip setup steps)
  ↓
Execute steps:
  - code_generate(new_feature)
  - Integrate với existing code
  ↓
Complete!

Progress Tracking

Galaxy CLI track progress qua file .galaxy/progress.json:

{
  "projectName": "Next.js E-commerce",
  "createdAt": "2025-01-10T10:00:00Z",
  "steps": [
    {
      "step": 1,
      "action": "Initialize Next.js",
      "status": "completed"
    },
    {
      "step": 2,
      "action": "Install dependencies",
      "status": "completed"
    },
    {
      "step": 3,
      "action": "Implement Product Catalog",
      "status": "in-progress"
    }
  ]
}

File chính:

• source/utils/progress-tracker.ts

Error Handling

Galaxy CLI có nhiều lớp error handling:

1. Tool level: Mỗi tool handle errors riêng
2. Agent level: Agents retry on failures
3. Orchestrator level: Fallback strategies
4. CLI level: User-friendly error messages

Performance Optimizations

• Lazy loading: Tools chỉ load khi cần
• Caching: BA analysis results cached
• Streaming: LLM responses streamed real-time
• Parallel execution: Multiple tools có thể chạy song song

Các bước tiếp theo

• AI Models & Roles - Chi tiết về từng AI agent
• Tools List - Danh sách đầy đủ tools
• Workflow - Hiểu luồng hoạt động chi tiết