# zte-aicloud/co-sight architecture

> Architecture diagram of the GitHub repository zte-aicloud/co-sight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zte-aicloud/co-sight
- Repository: https://github.com/zte-aicloud/co-sight

## Overview

##### Project type and purpose
- This is a full-stack AI research platform (“Co-Sight”) that mimics Manus:
- Frontend: Angular/TypeScript SPA under `cosight_ui/`
- Backend: Python web server (`cosight_server/`) exposing REST & WebSocket APIs
- Core logic & domain: in `app/` (agent dispatcher, planning, LLM orchestration, toolkits)
- Auxiliary CLI: `CoSight.py`, `llm.py`
- Packaging/deployment: Dockerfile, `.env_template`, build scripts under `tools/`

##### File structure
- Top-level: CLI entrypoints, Docker & env templates, Python package setup
- `app/agent_dispatcher`: layered DDD (application / domain / infrastructure) managing agent planning & execution
- `app/cosight`: core “agent” definitions, prompts, toolkits, LLM wrappers, task & record management
- `config/`: JSON & Python config for model endpoints & MCP server
- `cosight_server/`: two sub-apps
- `deep_research`: FastAPI routers, services, WebSocket manager
- `manus_server`: static UI hosting (index.html + web assets)
- `sdk/`: client SDK for external integration
- `cosight_ui/`: Angular project with modules, components, services, build tools
- `tools/`: spec files and Python build scripts

##### Insights from the README
- Describes one-click deployment, LLM configuration, search engine integration, MCP tool plugin
- Entry point: `cosight_server/deep_research/main.py`, HTTP port 7788, UI served at `/cosight/`
- Docker image workflow & environment variables

a. Main components
1. Frontend UI (cosight_ui): Angular app served as static assets
2. Web/API Server (cosight_server):
– RESTful routers (chat_manager, search, feedback, user_manager)
– WebSocket manager for real-time updates
– Manus server module for static UI hosting
3. Service Layer (inside `cosight_server/deep_research/service.py`): orchestrates requests
4. Agent Dispatcher (`app/agent_dispatcher`): application service, domain logic, infrastructure adapters
5. Core Cosight Logic (`app/cosight`):
– Agent definitions (actor, planner)
– Task & report management
– Toolkit library for tools (web search, file download, interpreters, etc.)
6. External Dependencies:
– LLM endpoints (OpenAI/Azure, local models)
– Search APIs (Google, Tavily)
– MCP micro-service (configurable external process)
7. Storage:
– In-memory or CSV persistence (`app/cosight/record`)
– Optional DB (if added) via infrastructure/entity models
8. Configuration & Deployment:
– Environment variables (`.env`)
– Config files (`config/mcp_server_config.json`)
– Docker container

b. Relationships & interactions
- UI ↔ HTTP API (REST calls for user actions, initial page load)
- UI ↔ WebSocket (real-time chat messages & updates)
- API Server → Service Layer → Agent Dispatcher → Domain & Toolkits
- Agent Dispatcher → External LLM APIs / Search APIs / MCP server
- Results flow back through layers → API → UI
- SDK module exposes client endpoints for third-party integration

c. Architectural patterns & design principles
- Layered + Domain-Driven Design (application / domain / infrastructure)
- Hexagonal/Ports-and-Adapters for tool integration (each toolkit or MCP is a “port”)
- Plugin/skill orchestration for extending agent capabilities (`skill` subpackages)
- SPA + backend API (separation of concerns)

d. Key technologies
- Frontend: Angular, TypeScript, WebSocket
- Backend: Python 3.11+, FastAPI (inferred from router structure), Uvicorn/Gunicorn
- LLM client wrappers (`app/cosight/llm/chat_llm.py`)
- Toolkits: custom modules under `app/cosight/tool`
- Docker, environment-based configuration, JSON config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend UI"
        direction TB
        UI["Frontend UI<br/>(Angular SPA)"]:::frontend
    end

    %% API Layer
    subgraph "API Server"
        direction TB
        API["API Server<br/>(Deep Research)"]:::api
        Routers["REST Routers"]:::api
        WS["WebSocket Manager"]:::api
        Service["Service Layer"]:::api
        Manus["Manus Static UI Host"]:::api
        SDK["Client SDK"]:::api
    end

    %% Agent Dispatcher DDD
    subgraph "Agent Dispatcher<br/>(DDD Layers)"
        direction TB
        AgentApp["Application Service"]:::domain
        AgentDomain["Domain"]:::domain
        AgentInfra["Infrastructure"]:::infra
    end

    %% Core Logic
    subgraph "Core Cosight Logic"
        direction TB
        CoreAgent["Agent Definitions & Orchestration"]:::domain
        LLMWrapper["LLM Wrappers"]:::domain
        TaskMgr["Task & Report Management"]:::domain
        Toolkit["Toolkit Library"]:::infra
        Record["Record Persistence"]:::infra
    end

    %% External Systems
    subgraph "External Dependencies"
        direction TB
        ExternLLM["LLM Providers"]:::external
        ExternSearch["Search APIs"]:::external
        ExternMCP["MCP Server"]:::external
    end

    %% Storage
    Storage(("Record Storage (CSV/DB)")):::external

    %% Config & Deployment
    subgraph "Config & Deployment"
        direction TB
        ConfigPy["Config Loader"]:::infra
        ConfigJson["MCP JSON Config"]:::infra
        Env["Env Template"]:::infra
        subgraph "CLI Entrypoints"
            direction TB
            MainCLI["Main CLI<br/>(CoSight.py)"]:::infra
            LLMCli["LLM CLI<br/>(llm.py)"]:::infra
        end
        subgraph "Packaging & Scripts"
            direction TB
            Docker["Dockerfile"]:::infra
            Build["build.py"]:::infra
            BuildWeb["build_web.py"]:::infra
            Spec1["Cosight.spec"]:::infra
            Spec2["NAE-Manus.spec"]:::infra
        end
    end

    %% Connections
    UI -->|REST HTTP| API
    UI <-->|WebSocket| WS
    API --> Routers
    Routers --> Service
    API --> Manus
    API --> SDK

    Service --> AgentApp
    AgentApp --> AgentDomain
    AgentApp --> AgentInfra
    AgentApp --> CoreAgent

    CoreAgent --> LLMWrapper
    CoreAgent --> TaskMgr
    CoreAgent --> Toolkit
    TaskMgr --> Record
    Record --> Storage

    AgentApp --> ExternLLM
    AgentApp --> ExternSearch
    AgentApp --> ExternMCP

    ConfigPy --> API
    ConfigJson --> ExternMCP
    Env --> Docker

    MainCLI --> LLMWrapper
    MainCLI --> AgentApp
    LLMCli --> LLMWrapper

    Docker --> API
    Docker --> UI

    %% Click Events
    click UI "https://github.com/zte-aicloud/co-sight/tree/master/cosight_ui/"
    click API "https://github.com/zte-aicloud/co-sight/tree/master/cosight_server/deep_research/"
    click Routers "https://github.com/zte-aicloud/co-sight/tree/master/cosight_server/deep_research/routers/"
    click WS "https://github.com/zte-aicloud/co-sight/blob/master/cosight_server/deep_research/routers/websocket_manager.py"
    click Service "https://github.com/zte-aicloud/co-sight/blob/master/cosight_server/deep_research/service.py"
    click Manus "https://github.com/zte-aicloud/co-sight/tree/master/cosight_server/manus_server/"
    click SDK "https://github.com/zte-aicloud/co-sight/tree/master/cosight_server/sdk/"
    click AgentApp "https://github.com/zte-aicloud/co-sight/tree/master/app/agent_dispatcher/application/"
    click AgentDomain "https://github.com/zte-aicloud/co-sight/tree/master/app/agent_dispatcher/domain/"
    click AgentInfra "https://github.com/zte-aicloud/co-sight/tree/master/app/agent_dispatcher/infrastructure/"
    click CoreAgent "https://github.com/zte-aicloud/co-sight/tree/master/app/cosight/agent/"
    click LLMWrapper "https://github.com/zte-aicloud/co-sight/blob/master/app/cosight/llm/chat_llm.py"
    click TaskMgr "https://github.com/zte-aicloud/co-sight/tree/master/app/cosight/task/"
    click Toolkit "https://github.com/zte-aicloud/co-sight/tree/master/app/cosight/tool/"
    click Record "https://github.com/zte-aicloud/co-sight/tree/master/app/cosight/record/"
    click ConfigPy "https://github.com/zte-aicloud/co-sight/blob/master/config/config.py"
    click ConfigJson "https://github.com/zte-aicloud/co-sight/blob/master/config/mcp_server_config.json"
    click Env "https://github.com/zte-aicloud/co-sight/blob/master/.env_template"
    click MainCLI "https://github.com/zte-aicloud/co-sight/blob/master/CoSight.py"
    click LLMCli "https://github.com/zte-aicloud/co-sight/blob/master/llm.py"
    click Docker "https://github.com/zte-aicloud/co-sight/tree/master/Dockerfile"
    click Build "https://github.com/zte-aicloud/co-sight/blob/master/tools/build.py"
    click BuildWeb "https://github.com/zte-aicloud/co-sight/blob/master/tools/build_web.py"
    click Spec1 "https://github.com/zte-aicloud/co-sight/blob/master/tools/Cosight.spec"
    click Spec2 "https://github.com/zte-aicloud/co-sight/blob/master/tools/NAE-Manus.spec"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef domain fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef infra fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
