updated docs

2026-04-14 10:32:05 -03:00
parent 2e5a304181
commit a80b72a9b1
67 changed files with 3260 additions and 5005 deletions
--- a/docs/data/en/artery.md
+++ b/docs/data/en/artery.md
@@ -0,0 +1,110 @@
+# 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"
+    }
+  ]
+}
+```