Architecture

System positioning, layers, and core modules. Base URL: https://api.nexalayer.net/v1

Architecture

NexaLayer (Agent Layer) is an intermediate layer between AI Agents and an existing proxy backend. It provides agent-friendly APIs and session abstraction while delegating user/order/proxy operations to the backend.

System positioning

┌──────────────────────────────────────────────────────┐
│                    AI Agent Ecosystem                │
│  Agent A    Agent B    Agent C    MCP / Others       │
└─────────────────────────┬────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────┐
│  AI Agent Network Execution Layer (Agent Layer)      │
│API Gateway→Auth/Session/Scheduling/Billing → Agent DB│
│                          │                           │
│               Internal HTTP Calls                    │
└─────────────────────────┬────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────┐
│    Existing IP Proxy Management System (Backend)     │
│User Management│Order Management│Proxy Service│Payment│
│         → Underlying Proxy Providers                 │
└──────────────────────────────────────────────────────┘

Responsibility split

Responsibility	Agent Layer	Backend
Agent auth (API Key / JWT)	✅	❌
Session lifecycle	✅	❌
Product/session recommendation	✅	❌
User/account creation	Proxy	✅
Order create / renew	Proxy	✅
Proxy IP allocation	Proxy	✅
Balance / recharge	Proxy	✅
Telemetry & health	✅	❌

Layered architecture

┌─────────────────────────────────────────────┐
│                 API Layer                    │
│  Routes → Validation (Zod) → Controller     │
├─────────────────────────────────────────────┤
│               Service Layer                  │
│  SessionService │ ProxyService               │
│  AccountService │ BillingService             │
├─────────────────────────────────────────────┤
│              Gateway Layer                   │
│  BackendClient (HTTP → 代理后端)             │
├─────────────────────────────────────────────┤
│             Data Access Layer                │
│  Prisma ORM → PostgreSQL (Agent DB)         │
└─────────────────────────────────────────────┘

Core modules

• Auth — API Key (X-API-Key) or JWT (Bearer). Per-key rate limit.
• Account — Register agent; 1:1 mapping to backend user; backend_user_id, backend_username, backend_token cache.
• Session — session_id, type (dynamic/static), status, proxy_config, rotation_policy, health (risk_level, health_score, success_rate), usage, expires_at.
• ProxyService — StaticProxyManager, DynamicProxyManager, SmartRouter; calls backend to create/renew/rotate/release proxies.
• Billing — getBalance, recharge, usage report; delegates to backend.
• Telemetry — reportEvent, batch, updateSessionHealth; stores events and drives health/recommendations.

Data flow (session create)

1. Agent calls POST /sessions with type and config.
2. Agent Layer validates, checks balance (via backend or cache), creates session row (status creating).
3. Agent Layer calls backend to create order / allocate proxy (async where applicable).
4. Backend returns order/proxy details; Agent Layer updates session (proxy_config, status active).
5. Agent polls GET /sessions/{session_id} or receives webhook until active, then uses proxy.full_url.

Next: Backend integration.