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

# System Architecture

> Dive into ChromaFlow's real-time neural architecture—Mermaid diagrams, data flows, scalability patterns, and security layers for enterprise deployment.

# Real-Time Enterprise Architecture

ChromaFlow's architecture is optimized for real-time, global-scale AI development. Deployed on Cloudflare's edge network, it combines Remix for routing, Durable Objects for state, and streaming protocols for instantaneous interactions—all while maintaining enterprise-grade security and observability.

<div class="doc-cards">
  <div class="doc-card">
    <span class="doc-badge">Edge-Optimized</span>
    <h3>Global Real-Time</h3>
    <p>Sub-50ms latency via Cloudflare Workers, SSE, and WebSockets for seamless collaboration.</p>
  </div>

  <div class="doc-card">
    <span class="doc-badge">Stateful Intelligence</span>
    <h3>Durable Objects</h3>
    <p>Persistent agent state across sessions, enabling multi-turn conversations and team sync.</p>
  </div>

  <div class="doc-card">
    <span class="doc-badge">Secure Scale</span>
    <h3>Enterprise Guardrails</h3>
    <p>Auth0 RBAC, RLS, and encrypted secrets ensure compliance at petabyte scale.</p>
  </div>
</div>

## Neural Architecture Diagram

```mermaid
graph TD
    A[User Request<br/>Remix Route] --> B[Auth0 Validation<br/>app/services/auth.server.ts]
    B --> C[LLM Orchestrator<br/>app/lib/.server/llm]
    C --> D[Claude Streaming<br/>SSE Response]
    C --> E[Tool Calls<br/>!search, !image]
    E --> F[Perplexity/Integrations<br/>API Routes]
    F --> G[Durable Object<br/>AgentStateManager]
    G --> H[WebSocket Broadcast<br/>Real-Time Updates]
    D --> I[Client Hydration<br/>React + Framer Motion]
    H --> I
    G --> J[Supabase Persistence<br/>Tokens & State]
    J --> K[Stripe Webhooks<br/>Billing Sync]
    L[Cloudflare Edge] -.-> A
    L -.-> G
    L -.-> J
```

This diagram illustrates the real-time flow: Requests hit edge-routed Remix actions, authenticate, orchestrate AI via streaming, persist state in Durable Objects, and broadcast updates via WebSockets—all executed globally.

## Real-Time Data Flow

1. **Ingress & Auth** – Requests land on Cloudflare Pages (`functions/[[path]].ts`), mounting Remix (`app/root.tsx`). Auth0 validates sessions server-side.

2. **Streaming Orchestration** – Chat endpoints (`app/routes/api.chat.ts`) initiate Claude streams. SSE delivers deltas; tool calls trigger parallel integrations.

3. **State Management** – Durable Objects (`app/lib/agents/core/agent-state-manager.ts`) handle WebSocket upgrades and message routing. Broadcast progress to subscribers.

4. **Integration Rail** – API routes (`app/routes/api.integrations.*`) execute OAuth, data sync, and webhooks with retries and observability.

5. **Egress & Persistence** – Responses stream to clients; state saves to Supabase. Edge caching minimizes latency.

**Latency Breakdown** (Enterprise Benchmarks):

| Component           | Avg Latency | 99th Percentile | Optimization            |
| ------------------- | ----------- | --------------- | ----------------------- |
| Edge Routing        | 5ms         | 12ms            | Cloudflare Anycast      |
| Auth Validation     | 20ms        | 50ms            | Token Caching           |
| LLM Streaming       | 80ms        | 150ms           | Model Sharding          |
| WebSocket Broadcast | 15ms        | 30ms            | Durable Object Affinity |
| DB Persistence      | 10ms        | 25ms            | Supabase Edge           |

## Scalability Patterns

* **Horizontal Scaling** – Cloudflare auto-scales Workers; Remix routes are stateless except for Durable Objects, which partition by ID for linear scaling.
* **Multi-Tenancy** – Tenant isolation via Auth0 organizations and Supabase RLS. Bind separate Durable Object namespaces per enterprise customer.
* **Caching Strategy** – Edge-side caching for static assets (Vite-built); Redis/Durable Storage for session data (TTL: 1h).
* **Load Balancing** – Global anycast routing; failover to secondary regions if latency >100ms.
* **Rate Limiting** – Per-user quotas enforced in middleware; Stripe-integrated billing for overages.

For 10k+ concurrent users: Deploy with `wrangler.toml` multi-region bindings; monitor via Cloudflare Analytics.

## Security Layers

ChromaFlow embeds defense-in-depth:

* **Identity** – Auth0 with MFA, anomaly detection, and just-in-time scopes.
* **API Gateway** – Remix middleware validates tokens, rate limits, and sanitizes inputs.
* **Data Protection** – Supabase RLS policies; encrypted secrets in Cloudflare KV. Stripe PCI compliance for payments.
* **Real-Time Security** – WebSocket origins validated; messages encrypted end-to-end. Durable Objects isolate tenant state.
* **Compliance** – SOC 2 ready; audit logs in Supabase for all actions. GDPR via data residency controls.

| Threat      | Mitigation                 | Monitoring      |
| ----------- | -------------------------- | --------------- |
| Token Theft | Short-lived JWTs, rotation | Auth0 logs      |
| DDoS        | Cloudflare WAF             | Rate metrics    |
| Data Leak   | RLS, encryption            | Supabase audits |
| Injection   | Input validation           | Sentry alerts   |

## Observability & Monitoring

* **Metrics** – `app/lib/.server/llm/monitoring.ts` exports Prometheus-compatible stats (tokens, latency, errors).
* **Tracing** – Distributed traces via Cloudflare Logs; integrate with Datadog/New Relic.
* **Alerts** – Webhook to Slack/Intercom on 5xx errors or quota breaches.
* **Health Checks** – `/health` endpoint verifies integrations and DB connectivity.

## Extensibility for Enterprise

* **Custom Agents** – Extend `AgentStateManager` for domain-specific logic; deploy as new Durable Object classes.
* **Federated Deployments** – Use Wrangler to create per-customer environments with isolated secrets.
* **API Extensions** – Add routes under `app/routes/api.custom.*`; auto-generate OpenAPI docs.

For architecture deep-dives, explore `architecture-diagram.html` or contact [architecture@chromaflow.ai](mailto:architecture@chromaflow.ai).

This blueprint powers ChromaFlow's real-time enterprise velocity—secure, scalable, and ready for orbit.