till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 21:41:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

🔧 chore: gitignore build artifacts and misc updates

Browse source 
- Add drizzle.config.* compiled files to gitignore
- Add packages/*/src/*.js patterns for compiled TS
- Update picture design tokens
- Update matrix-tts-bot storage state
- Add microservices API overview doc
This commit is contained in:
Till-JS 2026-01-29 18:37:42 +01:00
parent f6517733e2
commit 60b7cad508
5 changed files with 995 additions and 531 deletions
Download patch file Download diff file Expand all files Collapse all files

466
docs/MICROSERVICES_API_OVERVIEW.md Normal file
View file

@ -0,0 +1,466 @@
# ManaCore Microservices - API Overview
Dieses Dokument gibt einen Überblick über alle Microservices im ManaCore-Monorepo und beschreibt Optionen, diese als öffentliche APIs anzubieten.
## Inhaltsverzeichnis
1. [Service-Übersicht](#service-übersicht)
2. [Core Services (API-fähig)](#core-services-api-fähig)
3. [Bot Services](#bot-services)
4. [Aktuelle Architektur](#aktuelle-architektur)
5. [API-Strategien](#api-strategien)
6. [Empfehlung](#empfehlung)
---
## Service-Übersicht
| Service | Port | Typ | API-Ready | Beschreibung |
|---------|------|-----|-----------|--------------|
| **mana-core-auth** | 3001 | NestJS | ✅ | Zentrale Authentifizierung & Credits |
| **mana-search** | 3021 | NestJS | ✅ | Web-Suche & Content-Extraktion |
| **mana-stt** | 3020 | FastAPI | ✅ | Speech-to-Text (Whisper, Voxtral) |
| **mana-tts** | 3022 | FastAPI | ✅ | Text-to-Speech (Kokoro, F5-TTS) |
| Matrix Bots | 3310-3318 | NestJS | ❌ | Matrix-basierte Bots |
| Telegram Bots | 3300-3304 | NestJS | ❌ | Telegram-basierte Bots |
---
## Core Services (API-fähig)
Diese Services haben bereits REST-APIs und eignen sich für öffentliche Bereitstellung:
### 1. mana-core-auth (Port 3001)
**Zweck:** Zentrale Authentifizierung, JWT-Tokens, Credit-System
**Endpoints:**
```
POST /api/v1/auth/register - Benutzer registrieren
POST /api/v1/auth/login - Login (JWT erhalten)
POST /api/v1/auth/validate - Token validieren
POST /api/v1/auth/refresh - Token erneuern
GET /api/v1/auth/jwks - JWKS für Token-Verifikation
GET /api/v1/credits/balance - Credit-Guthaben
POST /api/v1/credits/use - Credits verbrauchen
```
**Stack:** NestJS + Better Auth + Drizzle + PostgreSQL + Redis
---
### 2. mana-search (Port 3021)
**Zweck:** Meta-Suchmaschine mit Content-Extraktion
**Endpoints:**
```
POST /api/v1/search - Web-Suche (Google, Bing, DuckDuckGo, etc.)
POST /api/v1/extract - URL-Inhalt extrahieren (Markdown)
POST /api/v1/extract/bulk - Bulk-Extraktion (max 20 URLs)
GET /api/v1/search/engines - Verfügbare Suchmaschinen
GET /health - Health Check
GET /metrics - Prometheus Metriken
```
**Stack:** NestJS + SearXNG + Redis (Cache: 1h Suche, 24h Extraktion)
**Beispiel-Request:**
```json
POST /api/v1/search
{
"query": "machine learning",
"options": {
"categories": ["general", "science"],
"engines": ["google", "wikipedia"],
"limit": 10
}
}
```
---
### 3. mana-stt (Port 3020)
**Zweck:** Audio-Transkription (optimiert für Deutsch)
**Endpoints:**
```
POST /transcribe - Whisper Large V3 Turbo
POST /transcribe/voxtral - Voxtral Mini (3B)
POST /transcribe/auto - Automatische Modellwahl
GET /models - Verfügbare Modelle
GET /health - Health Check
```
**Unterstützte Formate:** MP3, WAV, M4A, FLAC, OGG, WebM, MP4 (max 100MB)
**Stack:** Python + FastAPI + MLX (Apple Silicon optimiert)
**Beispiel-Request:**
```bash
curl -X POST http://localhost:3020/transcribe \
-F "file=@audio.mp3" \
-F "language=de"
```
---
### 4. mana-tts (Port 3022)
**Zweck:** Text-zu-Sprache Synthese
**Endpoints:**
```
POST /synthesize/kokoro - Schnelle Preset-Stimmen (30+)
POST /synthesize - F5-TTS Voice Cloning
POST /synthesize/auto - Automatische Modellwahl
GET /voices - Alle verfügbaren Stimmen
POST /voices - Custom Voice registrieren
DELETE /voices/{id} - Custom Voice löschen
GET /health - Health Check
```
**Modelle:**
- Kokoro-82M (~300MB): 30+ Preset-Stimmen, schnell
- F5-TTS (~6GB): Voice Cloning mit Referenz-Audio
**Stack:** Python + FastAPI + MLX (Apple Silicon optimiert)
**Beispiel-Request:**
```json
POST /synthesize/kokoro
{
"text": "Hallo Welt",
"voice": "af_heart",
"speed": 1.0,
"output_format": "mp3"
}
```
---
## Bot Services
Diese Services sind für Matrix/Telegram konzipiert, nicht als direkte APIs:
| Bot | Port | Funktion |
|-----|------|----------|
| matrix-mana-bot | 3310 | All-in-One (AI, Todos, Kalender) |
| matrix-ollama-bot | 3311 | LLM Chat (lokales Ollama) |
| matrix-stats-bot | 3312 | Analytics Reports |
| matrix-project-doc-bot | 3313 | Blog-Generierung |
| matrix-todo-bot | 3314 | Task Management |
| matrix-calendar-bot | 3315 | Kalender/Events |
| matrix-nutriphi-bot | 3316 | Ernährungs-Tracking |
| matrix-zitare-bot | 3317 | Zitate |
| matrix-clock-bot | 3318 | Timer/Alarme |
| matrix-tts-bot | 3023 | Sprachausgabe |
---
## Aktuelle Architektur
```
┌──────────────────────────────────┐
│ Clients │
│ (Web, Mobile, Bots) │
└────────────┬─────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ mana-core-auth│ │ mana-search │ │ mana-stt │
│ Port 3001 │ │ Port 3021 │ │ Port 3020 │
│ │ │ │ │ │
│ • Auth/JWT │ │ • Web Search │ │ • Whisper │
│ • Credits │ │ • Extraction │ │ • Voxtral │
│ • Stripe │ │ • SearXNG │ │ │
└───────────────┘ └───────────────┘ └───────────────┘
│ │
│ ┌───────────────────┤
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ mana-tts │ │ Matrix Bots │ │ Telegram Bots │
│ Port 3022 │ │ (10 Bots) │ │ (6 Bots) │
│ │ │ │ │ │
│ • Kokoro │ │ • GDPR-konform│ │ • Cloud-based │
│ • F5-TTS │ │ • Self-hosted │ │ │
└───────────────┘ └───────────────┘ └───────────────┘
```
---
## API-Strategien
### Option 1: Direkte Exposition (Einfach)
**Beschreibung:** Jeden Service direkt über eigenen Port/Subdomain exponieren.
```
api.mana.how/auth → mana-core-auth:3001
api.mana.how/search → mana-search:3021
api.mana.how/stt → mana-stt:3020
api.mana.how/tts → mana-tts:3022
```
**Vorteile:**
- Schnell umzusetzen
- Kein zusätzlicher Service
- Einfaches Debugging
**Nachteile:**
- Keine zentrale Rate-Limiting
- Keine einheitliche Auth
- Kein API-Key Management
- Schwierige Abrechnung
**Aufwand:** ~1-2 Tage (Nginx/Traefik Konfiguration)
---
### Option 2: API Gateway (Kong, Traefik, etc.)
**Beschreibung:** Zentraler Gateway vor allen Services.
```
┌─────────────────┐
│ API Gateway │
│ (Kong/Traefik)│
│ │
│ • Rate Limiting │
│ • API Keys │
│ • Logging │
│ • Metrics │
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
mana-auth mana-search mana-stt
```
**Vorteile:**
- Zentrale Authentifizierung
- Rate Limiting pro API-Key
- Request/Response Logging
- Einfache Abrechnung möglich
- SSL-Terminierung
**Nachteile:**
- Zusätzliche Infrastruktur
- Mehr Komplexität
- Single Point of Failure
**Empfohlene Tools:**
| Tool | Beschreibung | Aufwand |
|------|--------------|---------|
| **Kong** | Enterprise-ready, Plugin-System | Mittel |
| **Traefik** | Kubernetes-nativ, einfach | Gering |
| **APISIX** | High-performance, Lua-Plugins | Mittel |
| **Tyk** | Open Source, Dashboard | Mittel |
**Aufwand:** ~3-5 Tage
---
### Option 3: Custom API Service (NestJS)
**Beschreibung:** Eigener API-Service als Facade vor den Microservices.
```typescript
// api-gateway/src/app.module.ts
@Module({
imports: [
AuthModule, // API Key Validation
RateLimitModule, // Redis-based rate limiting
SearchModule, // Proxy zu mana-search
SttModule, // Proxy zu mana-stt
TtsModule, // Proxy zu mana-tts
BillingModule, // Credit/Usage tracking
],
})
export class AppModule {}
```
**Features:**
- API-Key Management (eigene DB-Tabelle)
- Usage Tracking pro Key
- Credit-System Integration
- Flexible Rate Limits
- Custom Transformationen
**Vorteile:**
- Volle Kontrolle
- Integration mit mana-core-auth
- TypeScript/NestJS Konsistenz
- Einfache Erweiterung
**Nachteile:**
- Mehr Entwicklungsaufwand
- Eigene Wartung
**Aufwand:** ~1-2 Wochen
---
### Option 4: Serverless/Edge (Cloudflare Workers)
**Beschreibung:** Edge-basierter API-Proxy mit Cloudflare Workers.
```javascript
// workers/api-proxy/src/index.ts
export default {
async fetch(request, env) {
const apiKey = request.headers.get('X-API-Key');
// Rate limiting via KV
const rateLimit = await env.RATE_LIMITS.get(apiKey);
if (rateLimit > 1000) {
return new Response('Rate limit exceeded', { status: 429 });
}
// Route to backend
const url = new URL(request.url);
if (url.pathname.startsWith('/v1/search')) {
return fetch(`https://search.internal.mana.how${url.pathname}`, request);
}
// ...
}
};
```
**Vorteile:**
- Global verteilt (Edge)
- Sehr schnell
- Auto-Scaling
- DDoS-Schutz inklusive
**Nachteile:**
- Vendor Lock-in
- Begrenzte Rechenzeit (50ms CPU)
- Nicht für lange Requests (STT/TTS)
**Aufwand:** ~3-5 Tage
---
### Option 5: Managed API Platform (Rapid API, etc.)
**Beschreibung:** APIs auf Marketplace-Plattform veröffentlichen.
**Plattformen:**
| Plattform | Vorteile | Nachteile |
|-----------|----------|-----------|
| **RapidAPI** | Große Reichweite, Abrechnung | 20% Commission |
| **AWS API Gateway** | AWS-Integration | Komplexität |
| **Google Cloud Endpoints** | GCP-Integration | Vendor Lock-in |
| **Azure API Management** | Enterprise Features | Kosten |
**Vorteile:**
- Sofortige Monetarisierung
- Bestehendes Billing
- Marketing/Discovery
**Nachteile:**
- Hohe Gebühren (15-20%)
- Weniger Kontrolle
- Vendor Lock-in
**Aufwand:** ~1 Woche
---
## Empfehlung
### Kurzfristig (MVP): Option 2 - Traefik API Gateway
```yaml
# docker-compose.api.yml
services:
traefik:
image: traefik:v3.0
command:
- "--api.dashboard=true"
- "--providers.docker=true"
- "--entrypoints.websecure.address=:443"
ports:
- "443:443"
labels:
- "traefik.http.middlewares.api-auth.plugin.apikey.headerName=X-API-Key"
- "traefik.http.middlewares.rate-limit.ratelimit.average=100"
mana-search:
labels:
- "traefik.http.routers.search.rule=Host(`api.mana.how`) && PathPrefix(`/v1/search`)"
- "traefik.http.routers.search.middlewares=api-auth,rate-limit"
```
**Warum Traefik?**
- Bereits im Stack (Docker-native)
- Einfache Konfiguration via Labels
- Built-in Rate Limiting
- Let's Encrypt Integration
- Dashboard für Monitoring
**Aufwand:** ~2-3 Tage
---
### Mittelfristig: Option 3 - Custom NestJS Gateway
Sobald komplexere Anforderungen entstehen:
- Flexible Pricing Tiers
- Usage-based Billing
- Webhook-Integrationen
- SDK-Generierung
**Struktur:**
```
services/
mana-api-gateway/
src/
modules/
auth/ # API Key Management
billing/ # Usage Tracking
proxy/ # Service Proxying
guards/
api-key.guard.ts
rate-limit.guard.ts
```
---
## Nächste Schritte
1. **Entscheidung:** Welche Option passt am besten?
2. **API Design:** OpenAPI Spec für alle Endpoints
3. **Pricing:** Tier-Modell definieren (Free/Pro/Enterprise)
4. **Documentation:** API-Docs mit Redoc/Swagger
5. **SDK:** Client-Libraries generieren (TypeScript, Python)
---
## Anhang: Port-Übersicht
| Port | Service | Typ |
|------|---------|-----|
| 3001 | mana-core-auth | Auth |
| 3020 | mana-stt | AI/ML |
| 3021 | mana-search | Search |
| 3022 | mana-tts | AI/ML |
| 3023 | matrix-tts-bot | Bot |
| 3300 | telegram-stats-bot | Bot |
| 3301 | telegram-ollama-bot | Bot |
| 3304 | telegram-todo-bot | Bot |
| 3310 | matrix-mana-bot | Bot |
| 3311 | matrix-ollama-bot | Bot |
| 3312 | matrix-stats-bot | Bot |
| 3313 | matrix-project-doc-bot | Bot |
| 3314 | matrix-todo-bot | Bot |
| 3315 | matrix-calendar-bot | Bot |
| 3316 | matrix-nutriphi-bot | Bot |
| 3317 | matrix-zitare-bot | Bot |
| 3318 | matrix-clock-bot | Bot |