Architecture Overview
FinClaw is built on a 100% cloud-native microservices architecture. Every service is compiled and packaged into a container image, then orchestrated by Docker Compose (single-machine) or Kubernetes (cluster). As a result, most ops capabilities — failover, dynamic scaling, resource management — are delivered by the container platform itself. FinClaw also relies on mature open-source components for data storage, caching, messaging, vector search, and time-series persistence.
Operations Architecture Diagram:
Architecture Components:
Infrastructure services:
- Relational DB: PostgreSQL (platform schemas — identity / inbox / persona / skill / document / pulse, etc.)
- Time-series DB: TimescaleDB (conversation-store)
- Cache & coordination: Redis
- Message bus: NATS (JetStream — cross-service events and reliable delivery)
- Vector search: Qdrant (enabled by runtime on demand)
- Text embeddings: TEI (Text Embeddings Inference)
- Durable timers / workflows: Restate (
ai-infra-rstimers and cron)
Container: Docker
Container orchestration: Docker Compose (single-machine), Kubernetes (cluster)
Logging:
- Single-machine: view container logs via
fleet.sh logs - Cluster / large-scale: Vector + Kafka + ElasticSearch + Kibana, or Loki + Grafana
- Single-machine: view container logs via
Monitoring: Prometheus + Grafana
FinClaw is organized into four layers — Application Interaction → Platform Control → Agent Engine → Infrastructure Foundation — bottom-up handling data/sandboxing, agent scheduling, tenancy and orchestration, and external integration. See Product Introduction for the overall architecture description.
Runtime Layers
| Layer | Representative Services | Port Range | Description |
|---|---|---|---|
| Gateway / Entry | api-gateway, ag-ui-server, openclaw-compat-gateway, feishu-connector | 261xx / 264xx | HTTP entry, SSE, channel integration |
| Core Platform | identity-service, orchestrator, claw-fleet-manager, persona-service, skill-service | 261xx | Authentication, flow orchestration, claw lifecycle, persona and skills |
| Conversation & Delivery | conversation-store, delivery, inbox-service, push-service, document-service, doc-toolkit | 262xx / 264xx | Conversation storage, delivery, inbox, push, documents |
| AI Runtime | ai-infra-rs | 26450 | Inference, tool invocation, memory, scheduling hooks |
Request Paths
- Inbound conversation (Flow A):
api-gateway → ag-ui-server → orchestrator → ai-infra-rs → delivery → (inbox-service / push-service / AG-UI stream)
See Deployment Components for the full service and port list.
Deployment Mode Comparison
FinClaw supports multiple deployment modes to match different scenarios and scales.
| Mode | Use Case | Architecture | Pros | Cons | Notes |
|---|---|---|---|---|---|
| Single-node | POC, test, light production | Docker Compose for all services | Fast to deploy, low cost | Limited performance, single point of failure | All services on one server |
| Small cluster | Production, HA | Kubernetes, 4 servers | High availability, good resource use | Resource contention | Services evenly distributed across 4 servers |
| Mid-to-large cluster | Scalability / DR requirements | Kubernetes, many servers, business / infra services separated | HA, good performance, no contention | Higher cost | Similar to small cluster, more servers, services separated |
| Dual-DC cold standby | Strong continuity requirements | Primary DC active, cold DC on standby | Strong DR, flexible failover | High cost, complex maintenance | Both DCs run K8s clusters; primary DC clustered infra, cold DC single-node sync |
Single-Node Deployment
In single-node mode, all services run on a single server. The Quick Installation Guide is based on this mode.
OS & Container Platform:
- Linux: foundation OS — provides a stable runtime and resource management.
- Docker: containerizes each microservice for isolation and portability.
- Docker Compose v2: defines and orchestrates multi-service deployments via
docker-compose.yml+fleet.sh, simplifying start/stop and log access.
Containers & System Components:
- API Gateway: the single external entrypoint (default
26100) — TLS termination, JWT validation, rate limiting, CSP. - Core / AI services: identity, orchestrator, ag-ui-server, ai-infra-rs and the rest — all on the
chatkit-networkcontainer network. - Data layer: PostgreSQL, TimescaleDB, Redis, NATS, TEI, Restate, all containerized, with state persisted via Docker volumes on the host data disk.
Server:
| Profile | CPU | Memory | Disk | Components | Count |
|---|---|---|---|---|---|
| Minimum | 8 cores | 16 GB | 200 GB | DB, cache, AI runtime, FinClaw microservices | 1 |
| Recommended | 16 cores | 32 GB | 300 GB (SSD) | DB, cache, AI runtime, FinClaw microservices | 1 |
System:
- CPU architecture: X86_64
- OS: CentOS 8+ / RHEL 8+ / Ubuntu 22.04+
Single-node throughput depends heavily on the external LLM provider's quota and latency. FinClaw's own bottleneck is usually
ai-infra-rsand the upstream LLM concurrency.
Cluster Deployment
Cluster deployment offers stronger HA, scalability, and DR.
1. Small Cluster
A small cluster delivers minimal HA on Kubernetes using 4 business servers — at most 1 may go down. Suitable for most customers with moderate HA and fault-isolation requirements.
| Purpose | CPU | Memory | Disk | Count |
|---|---|---|---|---|
| Business services | 8 cores | 16 GB | 500 GB | 4 |
| Ops management (optional) | 8 cores | 16 GB | 500 GB | 1 |
System:
- CPU: X86_64
- OS: CentOS 8+ / RHEL 8+ / Ubuntu 22.04+
Notes: services are evenly distributed across the 4 servers. Infrastructure (PostgreSQL / TimescaleDB / NATS / Redis) should be deployed as StatefulSets with persistent volumes; FinClaw microservices use Deployments + HPA for horizontal scaling.
2. Large-Scale Cluster
Suitable for customers with strong scalability and DR requirements. The architecture further strengthens fault isolation, recovery, and scalability — server count is unlimited, multi-active / multi-DC is supported, and sizing follows the business workload and DR plan.
Compared to a small cluster, the large-scale cluster delivers higher QPS, better overall performance, and stronger scalability.
System:
- CPU: X86_64
- OS: CentOS 8+ / RHEL 8+ / Ubuntu 22.04+
Notes: similar to the small cluster but with more servers, separating business services from infrastructure services — business nodes run FinClaw microservices while dedicated infra nodes run PG / Timescale / NATS / Redis / Qdrant / Temporal. Microservices use more replicas to absorb higher concurrent sessions and Pulse trigger volume.