# 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
```

![Artery Hierarchy](../graphs/artery_hierarchy.svg)

**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](artery-jira.md) | live | Issue tracker integration |
| [Google](artery-google.md) | building | OAuth, Sheets, Calendar, Drive |
| [Slack](artery-slack.md) | building | Channel messaging |
| [IA](artery-ia.md) | live | AI/LLM connector |
| Maps | planned | Location services |
| WhatsApp | planned | Messaging |
| GNUCash | planned | Accounting |
| VPN | planned | Network access |

## Shunts

| Shunt | Status | Description |
|-------|--------|-------------|
| [MercadoPago](artery-shunts.md) | ready | Mock payment processing API |
| [Example](artery-shunts.md) | ready | Template for creating new shunts |

See [Shunt Pattern](artery-shunts.md) 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`:

```python
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`:

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