feat: Architektur & Tech-Stack Dokumentation
📐 Architektur: - Cloud-basiert (SaaS) Entscheidung - Multi-Tenancy Konzept - Architektur-Diagramm 🛠️ Tech-Stack: - Deno + Oak Backend - PostgreSQL Datenbank - Vue 3 + PrimeVue Frontend - Hetzner Hosting (DSGVO) 📁 Projektstruktur: - src/ mit routes, middleware, services - docs/ mit Architektur-Doku - Basis main.ts mit Health Check
This commit is contained in:
103
docs/ARCHITECTURE.md
Normal file
103
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Pulse CRM - Architektur
|
||||
|
||||
## Übersicht
|
||||
|
||||
Pulse CRM ist eine cloud-basierte (SaaS) Customer Relationship Management Lösung, entwickelt für den deutschen Markt mit voller DSGVO-Konformität.
|
||||
|
||||
## Architektur-Diagramm
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CLIENTS │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Web App │ │ Mobile │ │ API │ │ Webhooks │ │
|
||||
│ │ (Vue 3) │ │ PWA │ │ Client │ │ │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
|
||||
│ │ │ │
|
||||
└─────────────┴──────┬──────┴─────────────┘
|
||||
│ HTTPS
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LOAD BALANCER │
|
||||
│ (nginx / Traefik) │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ API GATEWAY │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ Deno + Oak │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ Auth │ │ CORS │ │ Rate │ │ Logging │ │ │
|
||||
│ │ │Middleware│ │Middleware│ │ Limiter │ │ │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ API ROUTES │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ /auth │ │/contacts│ │ /deals │ │/pipeline│ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │/company │ │/activity│ │ /users │ │/settings│ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SERVICE LAYER │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ContactService│ │ DealService │ │ UserService │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ AuthService │ │ EmailService │ │ AuditService │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DATA LAYER │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ PostgreSQL │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ users │ │contacts │ │ deals │ │activities│ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │companies│ │pipelines│ │ orgs │ │audit_log│ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Entscheidungen
|
||||
|
||||
### Cloud vs. Client
|
||||
|
||||
**Entscheidung: Cloud-basiert (SaaS)**
|
||||
|
||||
| Kriterium | Cloud | Client |
|
||||
|-----------|-------|--------|
|
||||
| Installation | Keine | Erforderlich |
|
||||
| Updates | Automatisch | Manuell |
|
||||
| Wartung | Zentral | Pro Installation |
|
||||
| Zugriff | Überall | Nur lokal |
|
||||
| DSGVO | EU-Hosting | Kunde verantwortlich |
|
||||
| Skalierung | Einfach | Komplex |
|
||||
| Time-to-Market | Schnell | Langsam |
|
||||
|
||||
### Multi-Tenancy
|
||||
|
||||
**Shared Database, Separate Schemas** - Jeder Kunde (Organization) hat:
|
||||
- Eigene `org_id` in allen Tabellen
|
||||
- Row-Level Security in PostgreSQL
|
||||
- Isolierte Daten, geteilte Infrastruktur
|
||||
|
||||
## Hosting (DSGVO-konform)
|
||||
|
||||
- **Provider:** Hetzner Cloud
|
||||
- **Standort:** Falkenstein/Nürnberg, Deutschland 🇩🇪
|
||||
- **Backup:** Täglich, 30 Tage Retention
|
||||
- **Verschlüsselung:** TLS 1.3 (Transit), AES-256 (Rest)
|
||||
121
docs/TECH-STACK.md
Normal file
121
docs/TECH-STACK.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Pulse CRM - Tech Stack
|
||||
|
||||
## Backend
|
||||
|
||||
| Komponente | Technologie | Version | Begründung |
|
||||
|------------|-------------|---------|------------|
|
||||
| Runtime | **Deno** | 2.x | Sicher by default, TypeScript nativ, moderne APIs |
|
||||
| Framework | **Oak** | 17.x | Express-ähnlich, bewährt für Deno |
|
||||
| Datenbank | **PostgreSQL** | 16.x | ACID, JSON-Support, Row-Level Security |
|
||||
| ORM | **Drizzle ORM** | Latest | Type-safe, leichtgewichtig, gute DX |
|
||||
| Auth | **JWT** | - | Stateless, skalierbar |
|
||||
| Hashing | **Argon2** | - | Sicherster Passwort-Hash-Algorithmus |
|
||||
| Validation | **Zod** | 3.x | Runtime type validation |
|
||||
| Email | **Resend** | - | Moderne E-Mail API |
|
||||
|
||||
## Frontend
|
||||
|
||||
| Komponente | Technologie | Version | Begründung |
|
||||
|------------|-------------|---------|------------|
|
||||
| Framework | **Vue 3** | 3.5.x | Composition API, TypeScript, reaktiv |
|
||||
| UI Library | **PrimeVue** | 4.x | Enterprise-ready, umfangreich |
|
||||
| State | **Pinia** | 2.x | Offizieller Vue Store |
|
||||
| Router | **Vue Router** | 4.x | SPA Navigation |
|
||||
| HTTP | **Axios** | 1.x | HTTP Client |
|
||||
| Build | **Vite** | 5.x | Schnell, HMR, optimiert |
|
||||
| CSS | **TailwindCSS** | 3.x | Utility-first |
|
||||
| i18n | **vue-i18n** | 9.x | Mehrsprachigkeit (DE/EN) |
|
||||
|
||||
## Infrastruktur
|
||||
|
||||
| Komponente | Technologie | Begründung |
|
||||
|------------|-------------|------------|
|
||||
| Hosting | **Hetzner Cloud** | DSGVO, Deutschland, günstig |
|
||||
| Container | **Docker** | Portabilität, Reproduzierbarkeit |
|
||||
| Reverse Proxy | **nginx** | Performance, SSL Termination |
|
||||
| SSL | **Let's Encrypt** | Kostenlose Zertifikate |
|
||||
| CI/CD | **Gitea Actions** | Self-hosted, integriert |
|
||||
| Monitoring | **Prometheus + Grafana** | Open Source, bewährt |
|
||||
|
||||
## Datenbank Schema (Übersicht)
|
||||
|
||||
```sql
|
||||
-- Multi-Tenant Core
|
||||
organizations (id, name, settings, created_at)
|
||||
users (id, org_id, email, password_hash, role, ...)
|
||||
|
||||
-- CRM Core
|
||||
contacts (id, org_id, first_name, last_name, email, phone, company_id, ...)
|
||||
companies (id, org_id, name, industry, website, ...)
|
||||
deals (id, org_id, title, value, stage_id, contact_id, owner_id, ...)
|
||||
pipelines (id, org_id, name, stages JSONB, ...)
|
||||
|
||||
-- Activities
|
||||
activities (id, org_id, type, contact_id, deal_id, note, due_at, ...)
|
||||
|
||||
-- System
|
||||
audit_logs (id, org_id, user_id, action, entity, entity_id, changes, ...)
|
||||
```
|
||||
|
||||
## API Design
|
||||
|
||||
### RESTful Conventions
|
||||
|
||||
```
|
||||
GET /api/v1/contacts # Liste
|
||||
GET /api/v1/contacts/:id # Detail
|
||||
POST /api/v1/contacts # Erstellen
|
||||
PUT /api/v1/contacts/:id # Update
|
||||
DELETE /api/v1/contacts/:id # Löschen
|
||||
|
||||
# Nested Resources
|
||||
GET /api/v1/contacts/:id/activities
|
||||
POST /api/v1/deals/:id/move # Custom Action
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { ... },
|
||||
"meta": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 150
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Invalid email format",
|
||||
"details": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
- **Authentication:** JWT (Access Token 15min, Refresh Token 7d)
|
||||
- **Password:** Argon2id, min 8 chars
|
||||
- **Rate Limiting:** 100 req/min per IP, 1000 req/min per User
|
||||
- **CORS:** Whitelist allowed origins
|
||||
- **Input Validation:** Zod schemas for all inputs
|
||||
- **SQL Injection:** Parameterized queries via ORM
|
||||
- **XSS:** Content-Security-Policy headers
|
||||
- **HTTPS:** Enforced, HSTS enabled
|
||||
|
||||
## DSGVO Compliance
|
||||
|
||||
- ✅ Hosting in Deutschland (Hetzner)
|
||||
- ✅ Verschlüsselung (Transit + Rest)
|
||||
- ✅ Audit Logging
|
||||
- ✅ Datenexport (Art. 20)
|
||||
- ✅ Löschkonzept (Art. 17)
|
||||
- ✅ AVV-Vorlage für Kunden
|
||||
Reference in New Issue
Block a user