> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Architecture

> Profy system architecture overview: five core services, three-tier environments, and complete data flow

Profy uses a microservices architecture, splitting the three core capabilities of AI Agent creation, execution, and interaction into independently scalable service clusters. The entire platform runs on Tencent Cloud TKE (Kubernetes), with three environments (Test / UAT / Production) enabling safe progressive releases.

## Architecture Overview

```mermaid theme={null}
graph TB
    subgraph User Layer
        Browser[Browser/Client]
        IDE[IDE Plugin]
        IM[IM Platforms<br/>Feishu/DingTalk/WeCom]
    end

    subgraph Access Layer
        Nginx[Nginx Gateway<br/>Routing + TLS + Rate Limiting]
    end

    subgraph Application Services
        Web[Web Frontend<br/>Next.js SSR]
        Core[Core API<br/>Business Hub]
        Runtime[Agent Runtime<br/>AI Reasoning Engine]
        Marketing[Marketing Site<br/>SSR/ISR]
        Platform[Developer Platform<br/>API Management]
    end

    subgraph AI Execution Layer
        Sandbox[Cloud Sandbox<br/>Isolated Containers]
        LLM[LLM Services<br/>Multi-Provider Routing]
    end

    subgraph Data Layer
        PG[(PostgreSQL<br/>Business Data)]
        Redis[(Redis<br/>Cache/Queue)]
        COS[(Object Storage<br/>Files/Media)]
    end

    Browser --> Nginx
    IDE --> Nginx
    IM --> Nginx
    Nginx --> Web
    Nginx --> Core
    Nginx --> Marketing
    Nginx --> Platform
    Web --> Core
    Platform --> Core
    Core --> Runtime
    Runtime --> Sandbox
    Runtime --> LLM
    Core --> PG
    Core --> Redis
    Core --> COS
    Runtime --> Redis
```

## Five Core Services

<CardGroup cols={2}>
  <Card title="Web Frontend" icon="browser">
    A full-stack web application built on Next.js, serving as the user interface, server-side rendering layer, and BFF proxy. Horizontally scaled with multiple replicas, supporting canary releases.
  </Card>

  <Card title="Core API" icon="server">
    The business logic hub, providing dual-track REST + tRPC APIs built on the Hono framework. Handles authentication, billing, expert management, review pipelines, subscription systems, and all business orchestration.
  </Card>

  <Card title="Agent Runtime" icon="brain">
    An AI reasoning engine built in Python, implementing the Agent Loop with LangGraph. Responsible for context construction, tool scheduling, streaming output, self-evolution, and other core AI capabilities.
  </Card>

  <Card title="Cloud Sandbox" icon="cube">
    Provides an isolated cloud container environment for each AI conversation, pre-installed with development toolchains. Supports file persistence, network access, process isolation, and sub-second warm starts.
  </Card>

  <Card title="Marketing Site & Developer Platform" icon="globe">
    The marketing site is deployed with SSR/ISR, supporting real-time blog publishing. The developer platform provides API Key management, call logs, and usage analytics.
  </Card>
</CardGroup>

## Data Flow: From User to AI

A typical Expert conversation follows this path:

<Steps>
  <Step title="User sends a message">
    The user sends a message from the browser/IM/IDE, routed through Nginx to the Web frontend.
  </Step>

  <Step title="Core orchestrates the request">
    The Web frontend forwards the request to the Core API. Core performs identity authentication, credit verification, Expert configuration loading, and sandbox preparation, then sends the complete runtime payload to Agent Runtime.
  </Step>

  <Step title="Agent reasoning loop">
    The Runtime builds the context (message history + memory + skills + tool declarations) and calls the LLM for reasoning. If the model decides to use tools, the Runtime executes operations in the sandbox and feeds results back to the model for continued reasoning.
  </Step>

  <Step title="Streaming response">
    The entire process streams to the client in real time via Server-Sent Events (SSE) — the user sees the AI thinking and responding simultaneously, with tool execution results appearing in real time.
  </Step>
</Steps>

## Monorepo Structure

The entire codebase is organized as a Monorepo, sharing types and infrastructure:

```
profy/
├── apps/              # Frontend applications
│   ├── web/           # Main site (Next.js)
│   ├── platform/      # Developer platform
│   ├── marketing/     # Marketing site
│   └── desktop/       # Desktop client
├── services/          # Backend services
│   ├── core/          # Business API
│   ├── agent-runtime/ # AI reasoning engine
│   └── sandbox/ # Sandbox image engineering
├── packages/          # Shared packages
│   ├── types/         # TypeScript type definitions
│   ├── db/            # Database schema (single source of truth)
│   ├── auth/          # Shared auth configuration
│   └── ui/            # UI component library
└── deploy/            # Deployment configuration (K8s manifests)
```

<Tip>
  All database table definitions live in `packages/db` — the system's "single source of truth." Any service that needs data models imports from here, never redefining them.
</Tip>

## Three-Tier Environments and Release Strategy

| Environment    | Purpose                  | Characteristics                                    |
| -------------- | ------------------------ | -------------------------------------------------- |
| **Test**       | Development integration  | Rapid iteration, instability allowed               |
| **UAT**        | Pre-release verification | Same configuration as production, final gate       |
| **Production** | Live service             | Triggered by SemVer tags, supports canary rollouts |

Each environment runs in an independent Kubernetes namespace, sharing load balancer entry points but fully isolating data. Critical services (Web, Core, Runtime) support canary replicas — new versions are first validated with a small traffic percentage before full rollout.

## Multi-Provider Model Routing

Profy is not locked into a single LLM provider. Core has a built-in unified Provider management system that supports:

* **Multi-provider access**: Simultaneously connects to DashScope, Volcengine, Anthropic, OpenAI, and more
* **Smart routing**: Automatically selects the optimal key based on RPM/TPM quotas, balance, and health status
* **Token-aware scheduling**: Sliding window rate limiting to prevent saturating individual keys
* **Differentiated parameters**: Each model receives parameters according to its declared capabilities (e.g., temperature compatibility)

```mermaid theme={null}
graph LR
    Request[Inference Request] --> Router[Key Router]
    Router --> |Best RPM| Key1[Provider A - Key 1]
    Router --> |Sufficient Balance| Key2[Provider B - Key 2]
    Router --> |Health Check| Key3[Provider C - Key 3]
    Key1 --> LLM1[Model A]
    Key2 --> LLM2[Model B]
    Key3 --> LLM3[Model C]
```

## Supporting Infrastructure

<Accordion title="PostgreSQL — Business Data Persistence">
  Persistent storage for all business data, using Drizzle ORM for schema migration management. Supports optimistic locking for concurrency control, advisory locks for distributed mutual exclusion, and partitioned indexes for query performance optimization.
</Accordion>

<Accordion title="Redis — Caching and Real-Time Communication">
  Handles session caching, rate limit counters, distributed locks, worker task queues, real-time state synchronization, and more. Uses multi-key namespace isolation for different business domains.
</Accordion>

<Accordion title="COS Object Storage — Files and Media">
  All user-uploaded files, AI-generated media resources, and static assets are stored in Tencent Cloud COS. Buckets are isolated by environment, supporting pre-signed URL direct uploads and CDN acceleration.
</Accordion>

<Accordion title="IM Gateway — Multi-Platform Message Bridge">
  Provides unified access to Feishu, DingTalk, WeCom, and other IM platforms, converting messaging protocols into standard Agent calls so Experts can "live" in the communication tools users already use daily.
</Accordion>

## Design Philosophy

Profy's architecture follows several core principles:

1. **Separation of concerns**: Each service does one thing — Core doesn't do reasoning, Runtime doesn't handle billing, Sandbox doesn't touch business logic
2. **Declarative over imperative**: Expert capabilities are composed through declarations (skill Manifests, tool configurations) rather than hardcoded
3. **Progressive degradation**: When any external dependency is unavailable, core conversation capability should not be interrupted — if the sandbox is down, fall back to no-sandbox mode; if Redis is down, fall back to database
4. **Observability first**: Every request carries complete trace context, and every Agent decision step has an audit log

<Note>
  This is an actively evolving architecture. We continue to invest in three directions: reducing AI inference latency, improving sandbox cold-start speed, and enhancing multi-tenant isolation security.
</Note>