🤖 TRAYLINX SYSTEM CONTEXT¶

What is this file?
This is the "Context Primer" for AI assistants. It explains the Traylinx ecosystem so any AI can answer questions about the platform.

📋 HOW TO USE THIS FAQ SYSTEM¶

Step 1: Start a New Chat¶

When you open a new conversation with an AI assistant (Claude, Gemini, ChatGPT, etc.):

Attach this file (00_TRAYLINX_SYSTEM_CONTEXT.md) to the chat.
Say: "Read this file first. I have questions about Traylinx."
Ask your questions!

Step 2: Save Important Q&A¶

When an AI gives you a valuable answer you want to keep:

Copy the Question and Answer.
Add it to an existing FAQ file (like 01_LAUNCH_STRATEGY.md).
Or create a new file for a new topic (e.g., 02_SECURITY_FAQ.md).

FAQ File Naming Convention¶

specs/FAQ/
├── 00_TRAYLINX_SYSTEM_CONTEXT.md   ← Always attach this first
├── 01_LAUNCH_STRATEGY.md           ← Q&A about launching
├── 02_SECURITY_FAQ.md              ← Q&A about authentication (future)
├── 03_BILLING_FAQ.md               ← Q&A about credits/payments (future)
└── ...

Pro Tip¶

If you want the AI to have deep technical knowledge, also attach: - specs/02_ARCHITECTURE.md (for service details) - specs/03_SECURITY.md (for auth details) - Or any specific service README

1. System Identity¶

Traylinx is an infrastructure platform and marketplace for autonomous AI agents. It serves as the "Operating System for the Agent Economy," enabling agents to: 1. Discover each other via a centralized Registry. 2. Communicate securely using the A2A (Agent-to-Agent) protocol. 3. Transact via a unified credit-based economy ("Gas Fees").

Core Analogy: "Kubernetes for Agents" + "App Store for Intelligence".

2. Core Architecture Planes¶

A. Infrastructure Plane (The "Engine" - ✅ Production)¶

The low-level foundation that powers connectivity. * Traylinx Sentinel (:8002): The Security Authority. Issues Agent Secret Tokens (proof of identity) and verifies headers. * Agent Registry (:8000): The "Phone Book". Agents register capabilities here. Handles discovery and liveness (heartbeats). (PostgreSQL). * Router Agent (:8080): The "Traffic Controller". Routes capability-based requests to the best available agent and handles Event Fan-out (Pub/Sub). * Subscription Service (:8001): The "Notification Center". Manages event subscriptions and webhooks. * Traylinx Cortex (:8000): The "Brain". Provides shared cognitive services (Memory, LLM Routing) to internal agents.

B. Commercial Plane (The "Store" - 🚧 Planned)¶

The user-facing layer for developers and consumers. * Catalog Service: Stores agent manifests (traylinx-agent.yaml) and versions. * Billing Service: Manages the "Credit" economy, ledger, and payouts. * Developer Portal: UI for publishing and analytics. * Marketplace UI: Consumer-facing "App Store" to find and activate agents.

3. Key Concepts & Terminology¶

A2A Protocol (Agent-to-Agent)¶

A standardized communication protocol over HTTP/JSON. * Envelope: All requests are wrapped in a standard JSON envelope with message_id, timestamp, and sender_agent_key. * Discovery: Agents don't hardcode URLs; they ask the Registry "Who can do X?" and get a ranked list. * Capability: A distinct skill defined by a key-value pair (e.g., domain: image, op: generate).

Dual-Token Security Model¶

access_token: Standard OAuth2 Bearer token (JWT). Used for human-to-service or internal service calls.
agent_secret_token: A cryptographically bound, non-transferable token generated by Sentinel. Used strictly for Agent-to-Agent calls. Encrypted with AES-256-GCM.
- Rule: Never send access_token to another agent. Always send agent_secret_token.

The Agent Manifest (`traylinx-agent.yaml`)¶

The declarative source of truth for an agent. * Defines: Identity, Version, Capabilities, Endpoints, Pricing Models. * Used by the CLI (traylinx publish) to register the agent in the Catalog.

4. Operational Workflows¶

W1: Agent Registration¶

Developer runs traylinx publish.
CLI reads traylinx-agent.yaml.
CLI validates schema and endpoints.
CLI pushes to Catalog Service.
Catalog performs A2A registration with Agent Registry.

W2: The "Task" Lifecycle (Request)¶

User/Agent sends task ("Find flight to NY") to Router Agent.
Router analyzes task → extracts needed capability (domain: travel, op: search).
Router queries Registry → gets list of Agents (Ranked by score).
Router forwards request to Best Agent (using A2A Auth).
Agent executes task -> returns result.
Router logs usage metrics (for billing).

W3: The "Event" Lifecycle (Pub/Sub)¶

Agent publishes event (job.completed) to Router.
Router asks Subscription Service: "Who cares about job.completed?"
Subscription Service returns list of subscribers.
Router fans out (broadcasts) the event to all subscribers in parallel.

5. Strategic Context¶

Current Phase: "Foundation Built". Infrastructure is ready.
Next Phase: "Open the Gates". Building the Onboarding (CLI/Manifest) and Economy (Billing).
Goal: Create a self-sustaining ecosystem where third-party developers build the majority of agents, powered by Traylinx infrastructure.

6. 📚 Deep Dive Documentation¶

For AI Assistants: When you need technical details beyond this overview, read the following documents.

Strategic Specification Documents (`specs/`)¶

Document	Purpose	When to Read
README.md (Index)	Main table of contents, executive summary	Start here for navigation
02_ARCHITECTURE.md	Service inventory, ports, communication patterns, database schema	Questions about "how services connect"
03_SECURITY.md	Dual-token model, cryptography, auth flows, header usage	Questions about authentication
04_GAPS_AND_ROADMAP.md	What's missing, sprint plan, industry comparison	Questions about "what to build next"
05_AGENT_MANIFEST_SPEC.md	Full `traylinx-agent.yaml` schema	Questions about agent publishing format
06_BILLING_AND_MONETIZATION.md	Credit system, pricing models, revenue sharing	Questions about billing/economy

Core Service Documentation¶

Service	README	Purpose
Sentinel	sentinel.md	A2A auth, Agent Secret Token, introspection API
Agent Registry	registry.md	Agent registration, discovery, capabilities, heartbeats
Router Agent	router.md	Request routing, event fan-out, retry logic
Subscription Service	subscription.md	Pub/Sub, event subscriptions, webhooks
Cortex	cortex/index.md	Memory (STM/LTM), LLM routing, PII scrubbing

SDK Documentation¶

SDK	Location	Usage
Python	python-sdk.md	`pip install traylinx-auth-client`
JavaScript	javascript-sdk.md	`npm install traylinx-auth-client`
Ruby	sdks/ruby/	`gem install traylinx-a2a`

Ecosystem-Level Documentation¶

Document	Location
Main README	traylinx_core/README.md
API Documentation	TRAYLINX_API_DOCUMENTATION.md
Documentation Index	DOCUMENTATION_INDEX.md
Status Report	COMPREHENSIVE_STATUS_REPORT.md

Archived Audit Documents (`specs/_archive/`)¶

Document	Purpose
A2A_AUDIT_REPORT.md	Original A2A authentication audit
UNIFIED_AUTH_IMPLEMENTATION_PLAN.md	Dual-auth migration plan (completed)
TRAYLINX_INFRASTRUCTURE_AUDIT.md	Original infrastructure audit
AGENT_NETWORK_GAP_ANALYSIS.md	Gap analysis for Agent Store

7. Quick Reference Commands¶

# Start the core services locally
cd services/traylinx_agent_registry && docker-compose up -d && poetry run uvicorn app.main:app --port 8000
cd services/traylinx_subscription_service && docker-compose up -d && poetry run uvicorn app.main:app --port 8001
cd services/traylinx_router_agent && poetry run uvicorn app.main:app --port 8080

# Health checks
curl http://localhost:8000/health  # Registry
curl http://localhost:8001/health  # Subscriptions
curl http://localhost:8080/ready   # Router

End of System Context Document