kb-skills/.planning/codebase/ARCHITECTURE.md

# Architecture

**Analysis Date:** 2026-03-13

## Pattern Overview

**Overall:** Multi-skill workflow orchestration with skill-based modular architecture

**Key Characteristics:**
- Skill-based modular design: Each skill is an independent module with its own `SKILL.md` specification
- Pipeline workflow pattern: Sequential processing stages orchestrated by `kb-workflow`
- Stateful session management: tmux-based persistent sessions for GSD-OpenClaw
- Platform abstraction: Unified interfaces for multiple content platforms (Bilibili, Zhihu, YouTube, etc.)

## Layers

**Skill Definition Layer:**
- Purpose: Define skill capabilities, triggers, and execution steps
- Location: `kb-*/SKILL.md`, `gsd-openclaw/skill/SKILL.md`
- Contains: Markdown documents with YAML frontmatter and structured workflows
- Depends on: Nothing (declarative)
- Used by: AI agents that execute skills

**Core Implementation Layer:**
- Purpose: Implement actual functionality for each skill
- Location: `kb-*/*.py`, `gsd-openclaw/src/gsd_openclaw/*.py`
- Contains: Python modules with CLI entry points and core logic
- Depends on: External APIs, platform SDKs, AI providers
- Used by: Skill orchestration layer

**Orchestration Layer:**
- Purpose: Coordinate multiple skills in workflows
- Location: `kb-workflow/kb_workflow.py`
- Contains: Workflow coordination utilities, directory management, Git integration
- Depends on: All skill modules
- Used by: Main agent executing workflows

**Session Management Layer:**
- Purpose: Manage persistent tmux sessions for long-running operations
- Location: `gsd-openclaw/src/gsd_openclaw/tmux_session.py`
- Contains: TmuxSessionManager, session lifecycle management
- Depends on: libtmux, StateManager, WorkspaceManager
- Used by: GSD command orchestration

**State Persistence Layer:**
- Purpose: Provide crash-safe state checkpointing
- Location: `gsd-openclaw/src/gsd_openclaw/state_manager.py`
- Contains: StateManager, atomic save/load with backup rotation
- Depends on: File system only
- Used by: TmuxSessionManager, workspace management

## Data Flow

**Content Processing Pipeline:**

1. URL Input → `kb-link-parser` extracts platform, type, and ID
2. Metadata Extraction → Platform-specific skill (`kb-*-metadata`) fetches metadata
3. Content Download → Platform-specific skill (`kb-*-content`) downloads content
4. Speech Recognition → `kb-whisper`/`kb-funasr` transcribes audio (if needed)
5. Deep Analysis → `kb-deep-analyzer` generates AI-powered analysis report
6. Archive → `kb-workflow` archives to Git-managed directory

**GSD Session Flow:**

1. `/gsd:*` command received
2. `TmuxSessionManager.create_session()` or `resume_session()`
3. State persisted via `StateManager.save()`
4. Command executed in tmux session
5. Output captured and formatted via `FeishuResponseFormatter`

**State Management:**
- State stored in `~/gsd-workspaces/{project}/.gsd/state.json`
- Atomic writes via temp file + rename
- Automatic backup rotation (state.json → state.json.bak)

## Key Abstractions

**Skill:**
- Purpose: Represents an independent capability unit
- Examples: `kb-link-parser/link-parser.py`, `kb-deep-analyzer/deep_analyzer.py`
- Pattern: CLI-based with JSON output, defined by `SKILL.md` specification

**TmuxSession:**
- Purpose: Represents a managed tmux session for project isolation
- Examples: `gsd-openclaw/src/gsd_openclaw/tmux_session.py`
- Pattern: Dataclass with session_id, project_name, tmux_session_name

**Workspace:**
- Purpose: Isolated directory structure per project
- Examples: `gsd-openclaw/src/gsd_openclaw/workspace.py`
- Pattern: Defined subdirectories (.gsd/, code/, io-logs/)

**AnalysisResult:**
- Purpose: Structured output from deep analysis
- Examples: `kb-deep-analyzer/deep_analyzer.py`
- Pattern: Dataclass with summary, main_topics, key_insights, tags

## Entry Points

**CLI Entry Points:**
- Location: `kb-*/*.py` with `if __name__ == '__main__': main()`
- Triggers: Command-line invocation with argparse
- Responsibilities: Parse arguments, invoke core logic, output JSON

**gsd-ocl CLI:**
- Location: `gsd-openclaw/src/gsd_openclaw/cli.py`
- Triggers: `gsd-ocl create|list|destroy|resume|cleanup`
- Responsibilities: Session lifecycle management

**Skill Trigger:**
- Location: `SKILL.md` frontmatter with `name` and `description`
- Triggers: AI agent pattern matching on user messages
- Responsibilities: Define when and how to invoke the skill

## Error Handling

**Strategy:** Fail-fast with structured JSON error output

**Patterns:**
- All CLI tools output JSON with `success: true/false` field
- Error responses include `error` and `detail` fields
- Deep analysis failure terminates entire workflow (per `kb-workflow/SKILL.md`)
- State manager uses backup fallback on corruption

**Error Response Format:**
```json
{
  "success": false,
  "error": "Error description",
  "detail": "Additional context"
}
```

## Cross-Cutting Concerns

**Logging:** Console output with `[ModuleName]` prefixes (e.g., `[DeepAnalyzer]`, `[AI Client]`)

**Validation:**
- Environment variable checks before workflow execution (`kb-workflow/SKILL.md`)
- Required field validation in `StateManager.load()`
- Platform/type validation in link parser

**Authentication:**
- Platform cookies via environment variables (`BILIBILI_COOKIE`, `ZHIHU_COOKIE`)
- AI API keys via environment variables (`AI_API_KEY`, `HF_TOKEN`)
- Git credentials via environment variables (`KB_GIT_USER`, `KB_GIT_EMAIL`)

**Configuration:**
- Environment variables loaded from `~/.kb_env`
- Path configuration via environment variables (`KB_BASE_PATH`, `KB_ARCHIVE_PATH`, `KB_GIT_ROOT`)

---

*Architecture analysis: 2026-03-13*