Architecture¶
System Overview¶
The Traylinx platform consists of two planes:
- Infrastructure Plane — Core services that enable agent communication (✅ Production)
- Commercial Plane — Services for publishing, discovery, and monetization (🚧 Planned)
Stargate P2P Network¶
Stargate provides decentralized agent-to-agent communication with advanced NAT traversal capabilities:
- Circuit Relay v2 — Enables agents behind NAT to communicate via relay nodes
- NAT Detection — Automatic detection of network topology (public, private, symmetric NAT)
- Connection Pooling — Efficient connection reuse with automatic retry logic
- Health Monitoring — Real-time relay node health checks and failover
- Metrics Collection — Comprehensive instrumentation for monitoring and debugging
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) |
| Stargate | — | traylinx-stargate | P2P networking with NAT traversal |
| Relay Nodes | — | traylinx-stargate | Circuit Relay v2 infrastructure |
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)