> ## 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.

# Profy 系统架构与请求生命周期

> Profy 系统架构详解：Next.js Web 前端、Hono Core API、Agent Runtime 三层服务，配合 Monorepo 结构与完整的请求生命周期与调度路径。

Profy 采用 **Monorepo + 双层后端** 架构：**Web 前端（Next.js）** 负责 UI 渲染和 SSE 代理，**Core API（Hono + Bun）** 作为业务中台处理认证、金融、任务与 Sandbox 编排等所有业务逻辑，**Agent Runtime**（`services/agent-runtime`）在 **声明式 Sandbox（E2B/Docker）** 内运行 Expert 对话与工具执行。

## 概览

```mermaid theme={null}
graph TB
    Client["客户端<br/>(浏览器)"] --> Nginx["Nginx 反向代理"]

    Nginx -->|"/*"| Web["Web 前端<br/>Next.js 16"]
    Nginx -->|"/api/*"| Core["Core API<br/>Hono + Bun"]

    Web -->|"SSE 代理"| ExpertRT["Agent Runtime<br/>声明式 Sandbox（E2B/Docker）"]

    Core --> DB[(PostgreSQL)]
    Core --> Cache[(Redis)]
    Core --> Storage[(S3)]
    Core --> Pay["微信支付"]

    subgraph SharedPkgs["共享包 (packages/)"]
        Types["@profy/types"]
        DBPkg["@profy/db"]
        AuthPkg["@profy/auth"]
        UIPkg["@profy/ui"]
    end

    Core -.-> SharedPkgs
    Web -.-> SharedPkgs
```

* **Nginx** 作为统一入口，按路径分发到 Web 前端或 Core API
* **Web 前端** 负责页面渲染，同时作为 SSE 代理桥接用户与 Agent Runtime
* **Core API** 是所有业务逻辑的中枢 — 认证、金融、任务、市场、文件管理、Sandbox 编排
* **Agent Runtime** 在声明式 Sandbox（E2B/Docker）内为每个 Expert 提供隔离运行环境

## 技术栈

| 层级        | 技术                                   | 说明                          |
| --------- | ------------------------------------ | --------------------------- |
| **前端**    | Next.js 16, TypeScript, Tailwind CSS | SSR + CSR，i18n 支持           |
| **后端**    | Hono + Bun                           | 高性能 API 框架，REST + tRPC 双轨   |
| **ORM**   | Drizzle ORM                          | 类型安全的数据库访问                  |
| **认证**    | Better Auth + JWT                    | SMS OTP 登录，单设备策略            |
| **数据库**   | PostgreSQL                           | 主数据存储                       |
| **缓存**    | Redis                                | 会话缓存、验证码存储                  |
| **存储**    | S3 (COS)                             | 文件上传与对象存储                   |
| **Agent** | Agent Runtime                        | 声明式 Sandbox（E2B/Docker）隔离运行 |
| **部署**    | Docker Compose, Nginx                | 单机部署，蓝绿发布                   |
| **工具链**   | Bun, Biome, Lefthook                 | Monorepo 依赖管理、代码质量          |

## 核心模块

### Portal — 应用市场

面向终端用户的应用发现平台。支持分类浏览、搜索、收藏和技能管理。公开 API 无需登录即可访问，为用户提供零门槛的应用探索体验。

### Expert — AI 专家产品与运行时

**Expert** 是可售卖的 AI 专家产品单元；其对话与工具链由 **Agent Runtime** 在 **声明式 Sandbox** 中执行。Sandbox 由 Core 编排（创建、健康检查、暂停、终止），拥有隔离文件系统，经 SSE 与 Web 前端实时交互。

### Core API — 业务中台

Hono 构建的高性能后端，统一处理所有业务领域：

| 领域     | 能力                             |
| ------ | ------------------------------ |
| **认证** | SMS 验证码登录、JWT 管理、API Key       |
| **金融** | 积分体系、充值、微信支付、消费记录              |
| **任务** | 创建、提交、Expert / Sandbox 编排、付费查看 |
| **文件** | S3 对象存储、上传/下载                  |
| **市场** | 应用/技能 CRUD、分类、收藏               |

### Expert 沙箱与 agent-runtime

Core 是沙箱唯一编排层（create / provision / healthCheck / resume / pause / terminate），agent-runtime 仅提供纯基建操作（connect / 文件 / 命令执行）。所有 cloud 对话经 Core `prepare-invoke` 统一编排，异步 provision 通过 Redis 桥接给 Python。详见 [sandbox-runtime-contract.md](./sandbox-runtime-contract.md)。

## 请求生命周期

```mermaid theme={null}
sequenceDiagram
    participant User as 用户
    participant Nginx as Nginx
    participant Web as Web 前端
    participant Core as Core API
    participant Runtime as Agent Runtime

    User->>Nginx: 访问页面
    Nginx->>Web: 页面请求
    Web-->>User: HTML + JS

    User->>Nginx: API 调用
    Nginx->>Core: /api/* 请求
    Core-->>User: JSON 响应

    User->>Web: 发起 Expert 对话
    Web->>Runtime: SSE 连接
    Runtime-->>Web: 流式响应
    Web-->>User: 实时显示
```

## 下一步

<CardGroup cols={2}>
  <Card title="认证系统" icon="lock" href="/zh/documentation/auth">
    SMS 登录、JWT 管理与安全策略
  </Card>

  <Card title="Agent 平台" icon="robot" href="/zh/documentation/agent">
    Agent Runtime 与声明式 Sandbox 编排
  </Card>

  <Card title="应用市场" icon="store" href="/zh/documentation/marketplace">
    应用浏览、技能搜索与收藏
  </Card>

  <Card title="部署指南" icon="server" href="/zh/documentation/deployment">
    Docker Compose 部署与 Nginx 配置
  </Card>
</CardGroup>