Skip to content

System Architecture

CarvOS acts as the integration gateway between your ATS and Carv's AI services. This document describes the data flows and communication patterns.

System Overview

flowchart TB
    subgraph External["Your ATS"]
        ATS[ATS System]
    end

    subgraph CarvOS["CarvOS Gateway"]
        API[REST API]
        WH_IN[Webhook Receiver]
        WH_OUT[Webhook Sender]
    end

    subgraph Internal["Carv AI Services"]
        AI[AI Processing]
    end

    ATS -->|incoming webhooks| WH_IN
    ATS -->|REST requests| API
    WH_OUT -->|outgoing webhooks| ATS

    WH_IN --> AI
    AI --> WH_OUT
    API --> AI

Core Principles

Principle Description
Event-Driven Write operations are processed asynchronously
Sync Reads Read operations return data immediately
Webhook-First Primary integration method is webhooks
Signed Payloads All webhooks are cryptographically signed

Write Flow (Event-Driven)

When you send data to CarvOS, it's processed asynchronously:

sequenceDiagram
    participant ATS as Your ATS
    participant CarvOS
    participant AI as AI Services

    ATS->>CarvOS: POST /v1/webhooks/{ats_id}
    Note over ATS,CarvOS: X-Webhook-Signature: ...
    CarvOS->>CarvOS: Validate signature & schema
    CarvOS-->>ATS: 202 Accepted

    CarvOS->>AI: Process data
    AI->>AI: AI analysis
    AI->>CarvOS: Processing complete

    CarvOS->>ATS: Outgoing webhook (signed)

Write Flow Characteristics

Aspect Behavior
Immediate Response CarvOS validates and returns 202 Accepted immediately
Async Processing Data is processed by AI services asynchronously
Completion Notification Results delivered via outgoing webhook

Incoming Webhooks

Send webhooks to notify CarvOS of events in your ATS.

Endpoint Structure

POST /v1/webhooks/{ats_id}

Each ATS has a dedicated webhook endpoint identified by ats_id.

Authentication

Incoming webhooks use HMAC-SHA256 signature verification:

Header Format
X-Webhook-Signature t={timestamp},v1={signature}

Outgoing Webhooks

CarvOS sends webhooks to notify you of processed results.

Retry Policy

Attempt Delay
1 Immediate
2 1 minute
3 5 minutes
4 30 minutes
5 2 hours

Entity Model

Your Concept CarvOS Entity Description
Client Workspace Your customer's isolated environment
User Member Individual user within a workspace

Next Steps