111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# 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](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"
|
|
}
|
|
]
|
|
}
|
|
```
|