docs: add SaaS ↔ EaaS integration spec for Charon
Authentik group provisioning, Blesta user sync flow, port allocation, Docker image checklist, usage metering format. Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
12e15ae7e9
commit
0304c925a5
1 changed files with 146 additions and 0 deletions
146
docs/plans/2026-02-25-saas-eaas-integration-spec.md
Normal file
146
docs/plans/2026-02-25-saas-eaas-integration-spec.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# SaaS ↔ EaaS Integration Spec
|
||||
|
||||
**For**: Charon (lthn/saas setup on homelab)
|
||||
**From**: Virgil (lthn/eaas API development)
|
||||
**Date**: 25 February 2026
|
||||
|
||||
---
|
||||
|
||||
## What Charon Is Doing
|
||||
|
||||
Setting up the Host UK SaaS product suite on the homelab (Docker images), then building production images for de1 deployment:
|
||||
|
||||
- **Blesta** — customer billing, subscriptions, order management
|
||||
- **Authentik** — SSO, API key provisioning, group-based access control
|
||||
- **MixPost Enterprise** — social media scheduling
|
||||
- **66biolinks** — link-in-bio pages (lthn.ai landing funnel)
|
||||
- **66analytics** — privacy-respecting analytics
|
||||
|
||||
## What Virgil Needs From The Stack
|
||||
|
||||
### 1. Authentik ↔ Blesta Sync (CRITICAL PATH)
|
||||
|
||||
When a customer purchases an EaaS plan via Blesta, Authentik needs a corresponding user with the right group. This is the only hard integration.
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
Customer → Blesta checkout → Payment confirmed
|
||||
→ Blesta webhook/module creates Authentik user
|
||||
→ Assigns to group matching their plan tier
|
||||
→ Authentik issues API key
|
||||
→ Customer receives API key via email/dashboard
|
||||
```
|
||||
|
||||
**Authentik groups needed:**
|
||||
```
|
||||
eaas-dogfood — internal (Virgil, LEM training pipeline)
|
||||
eaas-free — 10 RPM, 100 RPD, heuristic + imprint only
|
||||
eaas-pro — 100 RPM, 10K RPD, all endpoints including judge
|
||||
eaas-enterprise — custom limits, all endpoints
|
||||
```
|
||||
|
||||
**What EaaS reads from Authentik** (via Traefik forward-auth headers):
|
||||
```
|
||||
X-authentik-uid → user ID (for rate limit tracking)
|
||||
X-authentik-groups → comma-separated group list (for tier check)
|
||||
X-authentik-username → display name (for usage logs)
|
||||
```
|
||||
|
||||
**Authentik API for user creation** (Charon can use this from Blesta module):
|
||||
```
|
||||
POST /api/v3/core/users/
|
||||
POST /api/v3/core/groups/{group_pk}/add_user/
|
||||
POST /api/v3/core/tokens/ → generates API key
|
||||
```
|
||||
|
||||
### 2. Blesta Usage Billing (NICE TO HAVE, NOT MVP)
|
||||
|
||||
EaaS writes usage logs to JSONL:
|
||||
```
|
||||
/var/log/eaas/usage.jsonl
|
||||
```
|
||||
|
||||
Format per line:
|
||||
```json
|
||||
{"ts":"2026-02-25T14:30:00Z","user":"uid","endpoint":"/v1/score/content","duration_ms":12,"suites":["heuristic"],"judge_used":false}
|
||||
```
|
||||
|
||||
Eventually Blesta needs a cron/module that:
|
||||
1. Reads usage JSONL, aggregates per user per day
|
||||
2. Reports usage against their plan quotas
|
||||
3. Triggers overage billing if applicable
|
||||
|
||||
**Not needed for MVP** — start with fixed plans, usage metering is just logging.
|
||||
|
||||
### 3. MixPost API Access (NICE TO HAVE)
|
||||
|
||||
For auto-posting training milestones and product announcements. Just need:
|
||||
- MixPost API endpoint accessible from de1
|
||||
- An API token with posting permissions
|
||||
- The workspace/account ID to post to
|
||||
|
||||
### 4. 66biolinks (NICE TO HAVE)
|
||||
|
||||
Landing page at lthn.ai for EaaS. Just needs to be deployed and accessible. No API integration needed — it's a static marketing page.
|
||||
|
||||
### 5. 66analytics (NICE TO HAVE)
|
||||
|
||||
Track docs page → signup conversion. Just needs the tracking script deployed on the EaaS documentation pages. No API integration.
|
||||
|
||||
## What Charon Does NOT Need To Worry About
|
||||
|
||||
- **66pusher** — not needed for API product
|
||||
- **66socialproof** — not needed for API devs
|
||||
- **Helpdesk/ticketing** — later
|
||||
- **EaaS binary itself** — Virgil builds this in lthn/eaas
|
||||
- **Model deployment** — models already on /Volumes/Data/lem/models/
|
||||
|
||||
## Infrastructure Notes
|
||||
|
||||
**de1 port allocation** (existing):
|
||||
```
|
||||
8000-8001 host.uk.com (Octane + Reverb)
|
||||
8003 lthn.io
|
||||
8004 bugseti.app
|
||||
8005-8006 lthn.ai
|
||||
8007 api.lthn.ai
|
||||
8008 mcp.host.uk.com
|
||||
9000/9443 Authentik
|
||||
```
|
||||
|
||||
**Suggested new ports:**
|
||||
```
|
||||
8009 eaas (Ethics-as-a-Service API)
|
||||
8010 blesta
|
||||
8011 mixpost
|
||||
8012 66biolinks
|
||||
8013 66analytics
|
||||
```
|
||||
|
||||
**Traefik routing for EaaS:**
|
||||
```
|
||||
Host(`api.lthn.ai`) && PathPrefix(`/v1/score`) → eaas:8009
|
||||
```
|
||||
|
||||
**Shared services (already running on de1):**
|
||||
```
|
||||
5432 PostgreSQL
|
||||
3306 Galera/MariaDB
|
||||
6379 Dragonfly (Redis-compatible)
|
||||
```
|
||||
|
||||
## Docker Image Checklist For Charon
|
||||
|
||||
- [ ] Blesta (with Authentik module/webhook)
|
||||
- [ ] MixPost Enterprise
|
||||
- [ ] 66biolinks
|
||||
- [ ] 66analytics
|
||||
- [ ] Confirm Authentik group provisioning works
|
||||
- [ ] Confirm Traefik labels/routing for each service
|
||||
- [ ] Test Blesta → Authentik user creation flow
|
||||
|
||||
## Questions For Charon
|
||||
|
||||
1. Does Blesta have a native Authentik/OIDC module, or do we need a custom webhook?
|
||||
2. What DB does Blesta want — MySQL/MariaDB (Galera) or PostgreSQL?
|
||||
3. Can MixPost share the existing Galera cluster or does it need its own DB?
|
||||
Loading…
Add table
Reference in a new issue