Architecture

---

System Overview

The Traylinx platform consists of two planes:

1. Infrastructure Plane — Core services that enable agent communication (✅ Production)
2. Commercial Plane — Services for publishing, discovery, and monetization (🚧 Planned)

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                          TRAYLINX AGENT NETWORK                             │
└─────────────────────────────────────────────────────────────────────────────┘

                           COMMERCIAL PLANE (Planned)
    ┌─────────────────────────────────────────────────────────────────────┐
    │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │
    │  │ Marketplace │  │  Developer  │  │   Catalog   │  │  Billing  │  │
    │  │     UI      │  │   Portal    │  │   Service   │  │  Service  │  │
    │  │   :3000     │  │   :3001     │  │   :8003     │  │   :8005   │  │
    │  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │
    └─────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
                         INFRASTRUCTURE PLANE (Production)
    ┌─────────────────────────────────────────────────────────────────────┐
    │                                                                      │
    │   ┌───────────────────────────────────────────────────────────┐     │
    │   │                    ROUTER AGENT :8080                      │     │
    │   │  • Capability-based request routing                        │     │
    │   │  • Event fan-out to 50+ subscribers                        │     │
    │   │  • Retry logic with fallback                               │     │
    │   └───────────────────────────────────────────────────────────┘     │
    │                          │                 │                         │
    │              ┌───────────┘                 └───────────┐             │
    │              ▼                                         ▼             │
    │   ┌─────────────────────┐               ┌─────────────────────┐     │
    │   │  AGENT REGISTRY     │               │  SUBSCRIPTION SVC   │     │
    │   │      :8000          │               │      :8001          │     │
    │   │                     │               │                     │     │
    │   │  • Agent discovery  │               │  • Pub/Sub events   │     │
    │   │  • Capability match │               │  • JSONB filtering  │     │
    │   │  • Performance rank │               │  • Wildcard match   │     │
    │   └─────────────────────┘               └─────────────────────┘     │
    │                                                                      │
    │   ┌───────────────────────────────────────────────────────────┐     │
    │   │                    TRAYLINX CORTEX :8000                   │     │
    │   │  • Short-Term Memory (Redis)      • LLM Routing (LiteLLM) │     │
    │   │  • Long-Term Memory (pgvector)    • PII Scrubbing         │     │
    │   │  • Context Management             • Background Tasks       │     │
    │   └───────────────────────────────────────────────────────────┘     │
    └─────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
                           SECURITY PLANE (Production)
    ┌─────────────────────────────────────────────────────────────────────┐
    │                     TRAYLINX SENTINEL :8002                         │
    │                                                                      │
    │   🔐 OAuth 2.0 Client Credentials    🔑 Agent Secret Token          │
    │   📊 Activity Monitoring             📋 Audit Logging               │
    │   ⏱️ Rate Limiting                   📤 Webhook Export              │
    └─────────────────────────────────────────────────────────────────────┘

---

Service Inventory

Core Infrastructure Services

Service	Port	Repository	Purpose
Sentinel	8002	traylinx_sentinel	Authentication & security
Router Agent	8080	traylinx_router_agent	Request routing + events
Agent Registry	8000	traylinx_agent_registry	Agent discovery
Subscription	8001	traylinx_subscription_service	Pub/sub events
Cortex	8000	traylinx_cortex	AI brain
Switch AI	—	switch_ai	AI gateway (Beta)

SDKs & Libraries

SDK	Package	Repository
Python	traylinx-auth-client	traylinx_auth_client_py
JavaScript	traylinx-auth-client	traylinx_auth_client_js
Ruby	traylinx-a2a	libs/a2a-ruby

---

Communication Patterns

Pattern 1: Request/Response Routing

Agent A                    Router                   Registry              Agent B
   │                         │                         │                     │
   │  POST /a2a/route        │                         │                     │
   │  {capabilities: [...]}  │                         │                     │
   │────────────────────────▶│                         │                     │
   │                         │  POST /a2a/discover     │                     │
   │                         │────────────────────────▶│                     │
   │                         │                         │                     │
   │                         │◀───────────────────────│  [Agent B, Agent C] │
   │                         │                         │                     │
   │                         │  POST /a2a/task         │                     │
   │                         │────────────────────────────────────────────▶│
   │                         │                         │                     │
   │                         │◀────────────────────────────────────────────│
   │◀───────────────────────│  {result: ...}          │                     │

Pattern 2: Event Publishing (Pub/Sub)

Publisher              Router              Subscription           Subscribers
    │                    │                    Service                  │
    │  POST /a2a/event   │                      │                      │
    │───────────────────▶│                      │                      │
    │                    │  POST /query         │                      │
    │                    │─────────────────────▶│                      │
    │                    │◀─────────────────────│ [Sub A, B, C]        │
    │                    │                      │                      │
    │                    │  ──── Fan-out (parallel) ─────────────────▶│
    │                    │                      │                      │
    │◀───────────────────│  {delivered: 3}      │                      │

---

Database Architecture

Service	Database	Purpose
Registry	PostgreSQL	Agent records, capabilities, stats
Subscription	PostgreSQL	Subscriptions with JSONB filters
Cortex STM	Redis 7	Session cache (short-term memory)
Cortex LTM	PostgreSQL + pgvector	Vector memory (long-term)
Sentinel	PostgreSQL	Activity logs, rate limits

Key Design Decision: PostgreSQL-only for core services (no Redis dependency except Cortex STM).

---

Quick Start

# 1. Agent Registry
cd traylinx_agent_registry
docker-compose up -d
poetry run alembic upgrade head
poetry run uvicorn app.main:app --port 8000

# 2. Subscription Service
cd traylinx_subscription_service
docker-compose up -d
poetry run alembic upgrade head
poetry run uvicorn app.main:app --port 8001

# 3. Router Agent
cd traylinx_router_agent
poetry run uvicorn app.main:app --port 8080

# 4. Health Checks
curl http://localhost:8000/health  # Registry
curl http://localhost:8001/health  # Subscriptions
curl http://localhost:8080/ready   # Router (checks deps)

---