> ## 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 system architecture and request lifecycle

> Inside the Profy monorepo: Next.js web frontend, Hono Core API, Agent Runtime, and the dual-layer backend that handles every request from auth to dispatch.

Profy uses a **Monorepo + dual-layer backend** architecture: **Web Frontend (Next.js)** handles UI rendering and SSE proxying, **Core API (Hono + Bun)** serves as the business middleware for auth, finance, and task management, and **Agent Runtime** (`services/agent-runtime`) runs **Experts** in **declarative sandboxes** (E2B/Docker).

## Overview

```mermaid theme={null}
graph TB
    Client["Client<br/>(Browser)"] --> Nginx["Nginx Reverse Proxy"]

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

    Web -->|"SSE Proxy"| Runtime["Agent Runtime<br/>Declarative Sandbox (E2B / Docker)"]

    Core --> DB[(PostgreSQL)]
    Core --> Cache[(Redis)]
    Core --> Storage[(S3)]
    Core --> Pay["WeChat Pay"]

    subgraph SharedPkgs["Shared Packages"]
        Types["@profy/types"]
        DBPkg["@profy/db"]
        AuthPkg["@profy/auth"]
        UIPkg["@profy/ui"]
    end

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

* **Nginx** serves as the unified entry point, routing by path to Web or Core API
* **Web Frontend** handles page rendering and acts as an SSE proxy bridging users with the Agent Runtime
* **Core API** is the hub for all business logic — auth, finance, tasks, marketplace, file management
* **Agent Runtime** executes Experts inside isolated declarative sandboxes (E2B/Docker)

## Tech Stack

| Layer        | Technology                           | Notes                                      |
| ------------ | ------------------------------------ | ------------------------------------------ |
| **Frontend** | Next.js 16, TypeScript, Tailwind CSS | SSR + CSR, i18n support                    |
| **Backend**  | Hono + Bun                           | High-performance API, REST + tRPC          |
| **ORM**      | Drizzle ORM                          | Type-safe database access                  |
| **Auth**     | Better Auth + JWT                    | SMS OTP login, single-device policy        |
| **Database** | PostgreSQL                           | Primary data store                         |
| **Cache**    | Redis                                | Session cache, OTP storage                 |
| **Storage**  | S3 (COS)                             | File uploads and object storage            |
| **Agent**    | Agent Runtime                        | Declarative sandbox (E2B/Docker) isolation |
| **Deploy**   | Docker Compose, Nginx                | Single-node deploy, blue-green             |
| **Tooling**  | Bun, Biome, Lefthook                 | Monorepo management, code quality          |

## Core Modules

### Portal — App Marketplace

A consumer-facing app discovery platform with category browsing, search, favorites, and skill management. Public APIs are accessible without authentication.

### Expert workforce — AI Experts & Agent Runtime

**Experts** (AI expert products) run on the **Agent Runtime** in **declarative sandboxes** (E2B/Docker), each with its own filesystem, communicating via SSE for real-time streaming conversations with tool calling and file operations. **Projects** coordinate multi-expert work; the **Marketplace** is the creator ecosystem surface.

### Core API — Business Middleware

High-performance Hono backend covering all business domains:

| Domain          | Capabilities                                        |
| --------------- | --------------------------------------------------- |
| **Auth**        | SMS OTP login, JWT management, API Key              |
| **Finance**     | Credit system, top-up, WeChat Pay, spending records |
| **Tasks**       | Create, submit, Agent dispatch, paid results        |
| **Files**       | S3 object storage, upload/download                  |
| **Marketplace** | App/skill CRUD, categories, favorites               |

## Request Lifecycle

```mermaid theme={null}
sequenceDiagram
    participant User as User
    participant Nginx as Nginx
    participant Web as Web Frontend
    participant Core as Core API
    participant Runtime as Agent Runtime

    User->>Nginx: Visit page
    Nginx->>Web: Page request
    Web-->>User: HTML + JS

    User->>Nginx: API call
    Nginx->>Core: /api/* request
    Core-->>User: JSON response

    User->>Web: Start Expert conversation
    Web->>Runtime: SSE connection
    Runtime-->>Web: Streaming response
    Web-->>User: Real-time display
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/en/documentation/auth">
    SMS login, JWT management, and security
  </Card>

  <Card title="Agent Platform" icon="robot" href="/en/documentation/agent">
    Agent Runtime and declarative sandbox lifecycle
  </Card>

  <Card title="Marketplace" icon="store" href="/en/documentation/marketplace">
    App browsing, skill search, and favorites
  </Card>

  <Card title="Deployment" icon="server" href="/en/documentation/deployment">
    Docker Compose deployment and Nginx configuration
  </Card>
</CardGroup>