Artery

Artery is the connector system. It bridges soleprint to external services -- APIs, messaging platforms, payment processors, AI providers.

Todo lo vital -- everything vital flows through here.

Hierarchy

Connectors scale from simple to full:

Vein ──────► Pulse ──────► Plexus
│            │              │
│            │              └── Full app: backend + frontend + DB
│            │
│            └── Composed: Vein + Room + Depot
│
└── Stateless API connector

Shunt ─── Fake connector for testing

Vein -- a stateless wrapper around an external API. Handles auth, exposes endpoints, runs standalone or through soleprint. Each vein follows the same structure: core/ for the isolated client, api/ for FastAPI routes, models/ for data types.

Shunt -- a mock vein. Returns configurable fake responses so you can test without hitting real APIs. Shunts mirror real API structures but store everything in memory.

Pulse -- a vein composed with a room and a depot. Adds persistent storage and room-specific configuration on top of a raw vein.

Plexus -- a full application. Backend, frontend, database. The highest level of the hierarchy.

Veins

Vein	Status	Description
Jira	live	Issue tracker integration
Google	building	OAuth, Sheets, Calendar, Drive
Slack	building	Channel messaging
IA	live	AI/LLM connector
Maps	planned	Location services
WhatsApp	planned	Messaging
GNUCash	planned	Accounting
VPN	planned	Network access

Shunts

Shunt	Status	Description
MercadoPago	ready	Mock payment processing API
Example	ready	Template for creating new shunts

See Shunt Pattern for how shunts work and how to create one.

Vein Structure

Every vein follows the same layout:

veins/
└── {name}/
    ├── __init__.py
    ├── main.py          # FastAPI app entry point
    ├── run.py            # Standalone runner
    ├── .env              # Credentials (not committed)
    ├── core/
    │   ├── config.py     # Pydantic settings from .env
    │   ├── client.py     # Isolated API client
    │   └── auth.py       # Auth handling
    ├── api/
    │   └── routes.py     # FastAPI router
    └── models/
        └── ...           # Data models, formatters

The core/ module is isolated. It can run without FastAPI. The api/ module wraps it in HTTP routes.

Base Class

All veins extend BaseVein:

class BaseVein(ABC):
    name: str                              # e.g., 'jira', 'slack'
    get_client(creds) -> client            # Create API client
    health_check(creds) -> dict            # Test connection
    create_router() -> APIRouter           # HTTP routes

Configuration

Veins load credentials from .env files using Pydantic settings. Credentials can also be passed per-request via HTTP headers, so one vein instance can serve multiple users.

Vein configurations are registered in veins.json:

{
  "items": [
    {
      "name": "jira",
      "slug": "jira",
      "title": "Jira",
      "status": "live",
      "system": "artery"
    }
  ]
}

3.5 KiB Raw Permalink Blame History