# wsshow/feikong-teams architecture

> Architecture diagram of the GitHub repository wsshow/feikong-teams, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wsshow/feikong-teams
- Repository: https://github.com/wsshow/feikong-teams

## Overview

#### Purpose and Entry Points
fkteams is a locally runnable Go multi-agent AI assistant for development, research, analysis, remote operations, and automation. The binary starts at `cmd/fkteams/main.go`; Cobra-style CLI commands expose interactive CLI/TUI, Web, API server, login, model management, sessions, skills, tools, and updates under `internal/adapters/transport/cli/commands/`. `fkteams web`/`serve` host the HTTP API and embedded React frontend.

#### Layering and Composition
The repository follows ports-and-adapters boundaries: domain types/events in `internal/domain/`, application orchestration in `internal/app/`, contracts in `internal/ports/`, and implementations in `internal/adapters/`. Bootstrap assembles configured runtimes, tools, skills, channels, schedulers, and environment dependencies through `internal/bootstrap/runtimes/runtimes.go`, `internal/bootstrap/tools/tools.go`, and `internal/bootstrap/services/`.

#### Agent Catalog and Task Orchestration
Agent definitions include coordinator, coder, researcher, analyst, tasker, moderator, and custom agents. The catalog/registry selects agent behavior and prompts from `internal/app/agent/catalog/registry.go` and `internal/app/agent/catalog/`; `internal/app/agent/runner.go` executes selected agents. Chat lifecycle and long-running task ownership—including interruption and queued follow-ups—are coordinated by `internal/app/chat/service.go` and `internal/app/chat/taskstream/manager.go`.

#### Runtime Execution Pipeline
The Eino runtime adapter is the primary agent execution engine: `internal/adapters/runtime/eino/engine/engine.go`, `internal/adapters/runtime/eino/runner.go`, and `internal/adapters/runtime/eino/factory.go`. It routes model messages and tool calls through middleware for dispatch, skills/context injection, summaries, steering, filesystem access, result trimming, patching, and destructive-operation checks. Runtime-facing abstractions preserve the boundary in `internal/ports/runtime/runtime.go`; turn execution, approvals, checkpoints, and event emission are handled in `internal/runtime/turn/`, `internal/runtime/approval/`, and `internal/runtime/events/`.

#### Models, Tools, and Extensions
Model providers are registered behind runtime provider adapters, including OpenAI-compatible services, Claude, Gemini, DeepSeek, Ollama, Qwen, Ark, OpenRouter, and GitHub Copilot (`internal/adapters/runtime/eino/providers/register/register.go`, `internal/adapters/model/providers/copilot/copilot.go`). Built-in tools cover filesystem, command execution, Git, SSH, search, documents, spreadsheets, scripts, and scheduling under `internal/adapters/tools/builtin/`. MCP clients (`internal/adapters/tools/mcp/client.go`) and SkillHub-backed skills (`internal/adapters/skill/skillhub/provider.go`) extend the tool/knowledge surface.

#### Persistence, Memory, and Scheduled Work
Local file storage persists sessions, transcripts, attachments, metadata, and memory via `internal/adapters/storage/file/history/`. Application memory extracts, ranks, injects, and manages long-term context in `internal/app/memory/`; the memory model adapter is `internal/adapters/model/memory/adapter.go`. Scheduled tasks are collected/executed in `internal/app/schedule/` and persist through the file-backed cron adapter at `internal/adapters/scheduler/filecron/scheduler.go`.

#### Transports and External Interfaces
The HTTP server routes chat, streaming/WebSocket events, OpenAI-compatible endpoints, session/file/share/skill/schedule APIs, authentication, and preview endpoints through `internal/adapters/transport/http/server.go`, `internal/adapters/transport/http/router/router.go`, and `internal/adapters/transport/http/handler/`. The embedded Bun/Vite React UI begins at `web/src/main.tsx` and drives task-stream chat from `web/src/features/chat/TaskStreamController.tsx`. CLI/TUI rendering consumes the same event model through `internal/adapters/transport/cli/runtime/`. Channel bridges connect Discord, QQ, and Weixin in `internal/adapters/transport/channel/`.

#### Runtime and Deployment Boundaries
The backend is Go; the embedded frontend is TypeScript/React built with Bun. Docker deployment is supplied by `Dockerfile` and `docker-compose.yml`. External dependencies include configured LLM providers, GitHub Copilot OAuth, optional MCP servers, SkillHub, Discord, QQ, Weixin, DuckDuckGo search, and local executables such as Git, SSH, Bun, and uv. Local workspace and tool policies are central security boundaries, enforced by command security, path guarding, approvals, and runtime tool policy.

Main entry points: [`internal/app/chat/service.go`](https://github.com/wsshow/feikong-teams/blob/main/internal/app/chat/service.go) (Chat service), [`internal/adapters/runtime/eino/engine/engine.go`](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/runtime/eino/engine/engine.go) (Eino engine), [`internal/bootstrap/runtimes/runtimes.go`](https://github.com/wsshow/feikong-teams/blob/main/internal/bootstrap/runtimes/runtimes.go) (Runtime bootstrap), [`cmd/fkteams/main.go`](https://github.com/wsshow/feikong-teams/blob/main/cmd/fkteams/main.go) (Go binary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Transports"]
  node_main["Go binary<br/>entrypoint<br/>[main.go]"]
  node_cli["CLI commands<br/>Cobra transport"]
  node_http["HTTP server<br/>HTTP transport<br/>[server.go]"]
  node_router["API router &amp; handlers<br/>HTTP API<br/>[router.go]"]
  node_web["React frontend<br/>Bun/Vite UI<br/>[main.tsx]"]
  node_taskstream_ui["Task-stream chat UI<br/>React controller"]
  node_channels["Channel bridges<br/>Discord/QQ/Weixin"]
end

subgraph group_app["Application Core"]
  node_bootstrap{{"Runtime bootstrap<br/>composition root<br/>[runtimes.go]"}}
  node_catalog["Agent catalog<br/>agent selection<br/>[registry.go]"]
  node_agent_runner["Agent runner<br/>application service<br/>[runner.go]"]
  node_chat["Chat service<br/>chat orchestration<br/>[service.go]"]
  node_task_manager["Task-stream manager<br/>task coordinator<br/>[manager.go]"]
end

subgraph group_runtime["Agent Runtime"]
  node_eino_engine["Eino engine<br/>agent engine<br/>[engine.go]"]
  node_runtime_port["Runtime port<br/>runtime contract<br/>[runtime.go]"]
  node_turns["Turn, approval &amp; events<br/>execution controls"]
end

subgraph group_extensions["Tools &amp; Providers"]
  node_providers["LLM providers<br/>model adapters<br/>[register.go]"]
  node_tools["Built-in tools<br/>tool adapters"]
  node_mcp["MCP clients<br/>external tool bridge<br/>[client.go]"]
  node_skills["SkillHub skills<br/>knowledge extension<br/>[provider.go]"]
end

subgraph group_state["State &amp; Scheduling"]
  node_memory["Memory service<br/>context management"]
  node_history[("File history storage<br/>local persistence")]
  node_schedule["Scheduled work<br/>scheduler"]
end

node_main -->|"starts"| node_cli
node_main -->|"composes"| node_bootstrap
node_cli -->|"submits chat"| node_chat
node_http -->|"serves"| node_router
node_router -->|"chat APIs"| node_chat
node_web -->|"mounts"| node_taskstream_ui
node_taskstream_ui -->|"streams tasks"| node_http
node_channels -->|"bridges messages"| node_chat
node_bootstrap -->|"registers"| node_providers
node_bootstrap -->|"assembles"| node_tools
node_bootstrap -->|"loads"| node_skills
node_chat -->|"coordinates"| node_task_manager
node_task_manager -->|"selects agent"| node_catalog
node_catalog -->|"configures"| node_agent_runner
node_agent_runner -->|"executes via"| node_runtime_port
node_runtime_port -->|"implemented by"| node_eino_engine
node_eino_engine -->|"runs controlled turns"| node_turns
node_eino_engine -->|"invokes models"| node_providers
node_eino_engine -->|"dispatches calls"| node_tools
node_eino_engine -->|"extends tools"| node_mcp
node_eino_engine -->|"injects context"| node_skills
node_chat -->|"uses context"| node_memory
node_memory -->|"persists"| node_history
node_chat -->|"stores sessions"| node_history
node_schedule -->|"triggers work"| node_chat

click node_main "https://github.com/wsshow/feikong-teams/blob/main/cmd/fkteams/main.go"
click node_http "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/transport/http/server.go"
click node_router "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/transport/http/router/router.go"
click node_web "https://github.com/wsshow/feikong-teams/blob/main/web/src/main.tsx"
click node_taskstream_ui "https://github.com/wsshow/feikong-teams/blob/main/web/src/features/chat/TaskStreamController.tsx"
click node_bootstrap "https://github.com/wsshow/feikong-teams/blob/main/internal/bootstrap/runtimes/runtimes.go"
click node_catalog "https://github.com/wsshow/feikong-teams/blob/main/internal/app/agent/catalog/registry.go"
click node_agent_runner "https://github.com/wsshow/feikong-teams/blob/main/internal/app/agent/runner.go"
click node_chat "https://github.com/wsshow/feikong-teams/blob/main/internal/app/chat/service.go"
click node_task_manager "https://github.com/wsshow/feikong-teams/blob/main/internal/app/chat/taskstream/manager.go"
click node_eino_engine "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/runtime/eino/engine/engine.go"
click node_runtime_port "https://github.com/wsshow/feikong-teams/blob/main/internal/ports/runtime/runtime.go"
click node_providers "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/runtime/eino/providers/register/register.go"
click node_mcp "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/tools/mcp/client.go"
click node_skills "https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/skill/skillhub/provider.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_http,node_router,node_web,node_taskstream_ui,node_channels toneBlue
class node_bootstrap,node_catalog,node_agent_runner,node_chat,node_task_manager toneAmber
class node_eino_engine,node_runtime_port,node_turns toneMint
class node_providers,node_tools,node_mcp,node_skills toneRose
class node_memory,node_history,node_schedule toneIndigo
```

## Components

### Entry & Transports

- [Go binary](https://github.com/wsshow/feikong-teams/blob/main/cmd/fkteams/main.go): entrypoint · `cmd/fkteams/main.go`
- **CLI commands**: Cobra transport · Interactive, server, login, model, session, skill, and tool commands.
- [HTTP server](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/transport/http/server.go): HTTP transport · Hosts APIs, streaming, WebSocket, and embedded web app. · `internal/adapters/transport/http/server.go`
- [API router & handlers](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/transport/http/router/router.go): HTTP API · `internal/adapters/transport/http/router/router.go`
- [React frontend](https://github.com/wsshow/feikong-teams/blob/main/web/src/main.tsx): Bun/Vite UI · `web/src/main.tsx`
- [Task-stream chat UI](https://github.com/wsshow/feikong-teams/blob/main/web/src/features/chat/TaskStreamController.tsx): React controller · `web/src/features/chat/TaskStreamController.tsx`
- **Channel bridges**: Discord/QQ/Weixin

### Application Core

- [Runtime bootstrap](https://github.com/wsshow/feikong-teams/blob/main/internal/bootstrap/runtimes/runtimes.go): composition root · Assembles configured runtimes, services, tools, skills, and channels. · `internal/bootstrap/runtimes/runtimes.go`
- [Agent catalog](https://github.com/wsshow/feikong-teams/blob/main/internal/app/agent/catalog/registry.go): agent selection · `internal/app/agent/catalog/registry.go`
- [Agent runner](https://github.com/wsshow/feikong-teams/blob/main/internal/app/agent/runner.go): application service · `internal/app/agent/runner.go`
- [Chat service](https://github.com/wsshow/feikong-teams/blob/main/internal/app/chat/service.go): chat orchestration · Owns chat lifecycle and long-running tasks. · `internal/app/chat/service.go`
- [Task-stream manager](https://github.com/wsshow/feikong-teams/blob/main/internal/app/chat/taskstream/manager.go): task coordinator · Coordinates interruption and queued follow-ups. · `internal/app/chat/taskstream/manager.go`

### Agent Runtime

- [Eino engine](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/runtime/eino/engine/engine.go): agent engine · Runs model turns and middleware-based tool workflows. · `internal/adapters/runtime/eino/engine/engine.go`
- [Runtime port](https://github.com/wsshow/feikong-teams/blob/main/internal/ports/runtime/runtime.go): runtime contract · `internal/ports/runtime/runtime.go`
- **Turn, approval & events**: execution controls · Handles checkpoints, approvals, and emitted events.

### Tools & Providers

- [LLM providers](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/runtime/eino/providers/register/register.go): model adapters · Registers configured hosted and local model providers. · `internal/adapters/runtime/eino/providers/register/register.go`
- **Built-in tools**: tool adapters · Filesystem, commands, Git, SSH, search, documents, and scheduling.
- [MCP clients](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/tools/mcp/client.go): external tool bridge · `internal/adapters/tools/mcp/client.go`
- [SkillHub skills](https://github.com/wsshow/feikong-teams/blob/main/internal/adapters/skill/skillhub/provider.go): knowledge extension · `internal/adapters/skill/skillhub/provider.go`

### State & Scheduling

- **Memory service**: context management · Extracts, ranks, injects, and manages long-term context.
- **File history storage**: local persistence · Persists sessions, transcripts, attachments, metadata, and memory.
- **Scheduled work**: scheduler · Collects and executes persisted scheduled tasks.

## Connections

- Go binary → CLI commands: starts
- Go binary → Runtime bootstrap: composes
- CLI commands → Chat service: submits chat
- HTTP server → API router & handlers: serves
- API router & handlers → Chat service: chat APIs
- React frontend → Task-stream chat UI: mounts
- Task-stream chat UI → HTTP server: streams tasks
- Channel bridges → Chat service: bridges messages
- Runtime bootstrap → LLM providers: registers
- Runtime bootstrap → Built-in tools: assembles
- Runtime bootstrap → SkillHub skills: loads
- Chat service → Task-stream manager: coordinates
- Task-stream manager → Agent catalog: selects agent
- Agent catalog → Agent runner: configures
- Agent runner → Runtime port: executes via
- Runtime port → Eino engine: implemented by
- Eino engine → Turn, approval & events: runs controlled turns
- Eino engine → LLM providers: invokes models
- Eino engine → Built-in tools: dispatches calls
- Eino engine → MCP clients: extends tools
- Eino engine → SkillHub skills: injects context
- Chat service → Memory service: uses context
- Memory service → File history storage: persists
- Chat service → File history storage: stores sessions
- Scheduled work → Chat service: triggers work