Core Platform

Enterprise-ready multitenantní aplikace postavená na Java 21 + Spring Boot 3.x s Keycloak autentifikací, React frontendem a PostgreSQL databází.

🏗️ Architektura

• Backend: Java 21, Spring Boot 3.5.x, Spring Security OAuth2
• Frontend: React 18, TypeScript, Vite
• Auth: Keycloak 25.x s custom theme
• Database: PostgreSQL 16 s Flyway migrations
• Monitoring: Native Loki UI + Prometheus stack (Grafana optional)
• Deployment: Docker Compose s SSL/HTTPS support

🏢 Multitenancy Features

Core Infrastructure

• Tenant-aware JWT: Automatická extrakce tenant informací z JWT tokenů
• Database filtering: Hibernate filtry pro úplnou datovou izolaci
• Caching: Optimalizované cachování tenant dat s TTL
• Logging: Tenant-aware logování s MDC kontextem

🌐 Subdomain Architecture

• 1 realm = 1 tenant: Každý tenant má vlastní Keycloak realm a subdoménu
• Wildcard SSL: *.core-platform.local certifikát pro neomezené subdomény
• Automatic routing: Nginx automaticky routuje {tenant}.core-platform.local na správný tenant kontext

🚀 Tenant Creation Workflow

1. Automatický setup (doporučeno)

# První setup - nastaví domény automaticky
make dev-setup

# Spustí celé prostředí
make up

# Vytvoření nového tenantu přes API
curl -X POST https://core-platform.local/api/admin/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"key": "acme-corp", "displayName": "ACME Corporation"}'

2. Manuální setup

# Přidat doménu pro nový tenant
make add-tenant-domain TENANT=acme-corp

# Nebo přímo scriptem
sudo scripts/setup-local-domains.sh add-tenant acme-corp

3. True Wildcard Support (macOS)

# Pro neomezené subdomény bez manuálního přidávání
make setup-wildcard

# Pak funguje JAKÁKOLI subdoména
# https://anything.core-platform.local

🎯 Tenant Management API

Vytvoření tenantu:

POST /api/admin/tenants
{
  "key": "acme-corp",
  "displayName": "ACME Corporation"
}

Seznam tenantů:

GET /api/admin/tenants

Smazání tenantu:

DELETE /api/admin/tenants/acme-corp

🔧 Domain Management Commands

# Ukázat současnou konfiguraci domén
make show-domains

# Přidat doménu pro tenant
make add-tenant-domain TENANT=my-company

# Odebrat doménu tenantu  
make remove-tenant-domain TENANT=my-company

# Nastavit wildcard support (macOS)
make setup-wildcard

🚀 Quick Start

Development Mode (Hot Reload - DOPORUČENO)

# 1. První setup (jednou)
make dev-setup     # Nastaví SSL, domény, atd.

# 2. Start vývojového prostředí
make dev-up        # Automatický hot reload

# 3. Sleduj logy
make logs-backend  # Backend logy (Loki)
make logs-frontend # Frontend logy

# 4. Změny v kódu se automaticky aplikují!

Production-like Mode (s Build Doctorem)

# Start s automatickou verifikací
make up            # Build + Start + Smoke tests

# Rebuild s verifikací (FAST ⚡ - používá cache)
make rebuild       # 3-5x rychlejší než dřív!

# Force rebuild (slow but clean - bez cache)
make rebuild-clean # Používej jen při problémech s dependencies

# Manuální verifikace
make verify        # Rychlé smoke testy (~15s)
make verify-full   # Plné integration testy (~3min)

Pre-flight kontroly lze v CI přeskočit:

SKIP_DOCTOR=true make build

⚡ Build Optimization: make rebuild nyní používá Docker cache, což znamená:

• Dependencies se stahují pouze jednou
• Běžné změny v kódu = rebuild za ~2-3 minuty místo ~10 minut
• První build (~10 min), další buildy (~2-3 min) - 3-5x rychlejší!
• Používej make rebuild-clean pouze při změnách v pom.xml/package.json

Více v BUILD_OPTIMIZATION_IMPLEMENTATION.md

Po úspěšném make up se automaticky spustí smoke testy, které ověří:

• ✅ Container health
• ✅ API endpoints
• ✅ Frontend přístupnost
• ✅ Observability stack
• ✅ Keycloak konfigurace

Více v docs/POST_DEPLOYMENT_VERIFICATION.md

Příprava

# Zkopíruj environment konfiguraci
cp .env.example .env

Spuštění

# Build a spustí všechny služby
docker compose up --build -d

# Sledování logů
docker compose logs -f backend keycloak

🔄 Správa Dat a Restartů

Typy Restartů

Core Platform nabízí různé možnosti restartu podle vašich potřeb:

🔄 Běžný Restart (Zachová VŠECHNA data)

make restart

• Standardní restart pro běžný vývoj
• Zachová: Keycloak customizace, databázová data, uživatelská nastavení
• Použití: Denní vývoj, po změnách kódu

🆕 Fresh Start (Smaže JEN Keycloak data)

make fresh

• Smaže pouze Keycloak data, zachová aplikační databázi
• Zachová: Všechna aplikační data v PostgreSQL
• Smaže: Keycloak realms, uživatele, role, customizace
• Použití: Reset autentifikace při zachování app dat
• ⚠️ 5 sekund na zrušení

🔄 Reset Keycloak

make reset-kc

• Rychlý reset pouze Keycloak do výchozího stavu
• Obnoví základní realm a test uživatele
• ⚠️ 3 sekundy na zrušení

💾 Reset Databáze

make reset-db

• Smaže pouze aplikační data, zachová Keycloak
• Zachová: Keycloak nastavení, uživatele, role
• Smaže: Aplikační data v PostgreSQL
• ⚠️ 3 sekundy na zrušení

🧹 Úplné Čištění

make clean

• SMAŽE VŠECHNA DATA + rebuild všech images
• Kompletně čisté prostředí od začátku
• Použití: Před důležitými testy, po velkých změnách

Správa Keycloak Customizací

⚠️ Ztráta Customizací

Pokud si v Keycloak admin konzoli upravíte uživatele, role nebo nastavení:

• make restart → Vaše změny ZŮSTANOU ✅
• make fresh → Vaše změny SE ZTRATÍ ❌
• make reset-kc → Vaše změny SE ZTRATÍ ❌
• make clean → Vaše změny SE ZTRATÍ ❌

💡 Best Practices

# Pro běžný vývoj - zachová customizace
make restart

# Pro testování s čistým Keycloak
make reset-kc

# Pro kompletní reset prostředí
make clean

🔒 Výchozí Přihlašovací Údaje

Po každém reset Keycloak (fresh, reset-kc, clean):

Keycloak Admin:

• URL: http://localhost:8081/admin
• Username: admin
• Password: admin123

Test uživatelé:

• Username: test / Password: Test.1234
• Username: test_admin / Password: Test.1234

📊 API Endpoints

Public API

• GET /api/tenants/me - Current tenant info
• GET /api/users/me - Current user info
• GET /api/users/search?q= - Search users in tenant

🧪 Testing

Test Structure

core-platform/
├── backend/src/test/          # Backend unit tests (JUnit 5)
├── frontend/src/**/*.test.tsx # Frontend unit tests (Vitest)
├── e2e/                       # E2E tests (Playwright)
│   ├── specs/pre/             # PRE-DEPLOY smoke tests
│   └── specs/post/            # POST-DEPLOY full E2E
└── tests/                     # Legacy integration tests

Quick Commands

# Unit Tests
make test-backend    # Backend unit tests
make test-frontend   # Frontend unit tests
make test-all       # All unit tests

# E2E Tests (Playwright)
make e2e-setup      # Install E2E dependencies (jednou)
make test-e2e-pre   # PRE-DEPLOY smoke (5-7 min)
make test-e2e-post  # POST-DEPLOY full (20-30 min)
make test-e2e       # All E2E tests
make e2e-report     # View HTML report

# CI/CD
make ci-test-pipeline  # Full CI pipeline (unit + E2E gate)
make ci-post-deploy    # Post-deployment validation

Two-Tier E2E Strategy

PRE-DEPLOY (Fast Gate - 5-7 min):

• ✅ Login & authentication flow
• ✅ Menu RBAC validation
• ✅ Entity CRUD operations
• ✅ Workflow panel UI

POST-DEPLOY (Full E2E - 20-30 min):

• ✅ Auth + profile updates
• ✅ Entity creation via Studio
• ✅ Workflow execution
• ✅ Directory consistency
• ✅ Cleanup verification

Testing URLs

Local Development:

# PRE & POST tests na lokálním prostředí
make test-e2e-pre   # uses https://core-platform.local
make ci-post-deploy # uses https://core-platform.local

Staging/Production:

# POST tests na nasazeném prostředí
POST_BASE_URL=https://staging.your-domain.com make ci-post-deploy

Test Credentials

• Regular user: test / Test.1234
• Admin user: test_admin / Test.1234

Documentation

• 📖 TESTING_STRUCTURE.md - Complete testing guide
• 📖 TESTING_FAQ.md - Frequently asked questions
• 📖 E2E_MAKEFILE_INTEGRATION.md - E2E details
• 📖 e2e/README.md - Playwright setup

🔍 Kvalita kódu & preflight checks

Před každým commitem je důležité spustit kontroly kvality kódu, aby se předešlo chybám v runtime.

Povinné kontroly před commitem

# Spusť v adresáři frontend/
npm run lint && npm run typecheck

Detailní popis kontrol

ESLint - kontroluje:

• ✅ Správnost importů a exportů (default vs named)
• ✅ Neexistující moduly a komponenty
• ✅ React best practices (hooks rules, JSX syntax)
• ✅ Nepoužité proměnné a importy

TypeScript typecheck - kontroluje:

• ✅ Typovou správnost kódu
• ✅ Kompatibilitu importů s esModuleInterop: false
• ✅ Správnost cest a aliasů

VS Code integrace

Projekt má nakonfigurované .vscode/settings.json pro:

• 🔄 ESLint validaci v reálném čase (onType)
• 🎯 Použití workspace TypeScript verze
• ⚡ Okamžité zvýraznění chyb v editoru

Runtime safety

Aplikace obsahuje:

• 🛡️ ErrorBoundary - zachytává chyby komponent místo pádu celé aplikace
• 🔒 Component guards - kontrolují platnost komponent před renderem
• 📋 Jasné error hlášky - místo cryptic React error #130

CI/CD integrace

V CI pipeline by měly být tyto kroky povinné:

- name: Lint check
  run: npm run lint
- name: Type check  
  run: npm run typecheck

Poznámky k nastavení

• allowSyntheticDefaultImports a esModuleInterop jsou dočasně vypnuty pro přísné odhalení default/named záměn
• Po vyčištění všech chyb lze tyto volby vrátit na true pro pohodlnější development
• CI musí i nadále procházet bez chyb

📋 Troubleshooting

General Issues

1. Services not starting:

   • Zkontroluj Docker logy: docker compose logs
   • Ověř dostupnost portů: lsof -i :8080,8443,5432
   • Zkontroluj disk space: docker system df

2. Authentication issues:

   • Ověř Keycloak admin credentials
   • Zkontroluj realm configuration
   • Zkontroluj JWT token validitu

3. Database connectivity:

   • Ověř PostgreSQL connection string
   • Zkontroluj database credentials
   • Sleduj logy: docker logs core-db

🌐 Síťová Architektura

Rozdělení External vs Internal sítě

⚠️ DŮLEŽITÉ: Nepomíchej externí domény s interní Docker sítí!

🌍 EXTERNÍ - Uživatelské URL (před nginx)

https://admin.core-platform.local      → Admin frontend + Keycloak admin realm
https://tenant1.core-platform.local    → Tenant1 frontend + tenant1 realm  
https://tenant2.core-platform.local    → Tenant2 frontend + tenant2 realm
https://company-a.core-platform.local  → Company-A frontend + company-a realm

🐳 INTERNÍ - Docker síť (za nginx)

nginx:443 → frontend:80    (React app)
nginx:443 → backend:8080   (Spring Boot API)  
nginx:443 → keycloak:8443  (Keycloak server - HTTPS)
nginx:443 → db:5432        (PostgreSQL)

🔧 Konfigurace pravidla:

Komponenta	Externí doména	Interní hostname	Účel
Nginx	*.core-platform.local:443	nginx:443	Revere proxy + SSL termination
Frontend	Přes nginx	frontend:80	React SPA
Backend	Přes nginx /api/*	backend:8080	REST API
Keycloak	Přes nginx /realms/*, /admin/*	keycloak:8443	Auth server
Database	Nedostupná zvenčí	db:5432	PostgreSQL

🎯 Keycloak konfigurace:

# ✅ SPRÁVNĚ - Keycloak hostname je interní Docker název
KC_HOSTNAME: keycloak  # nebo admin.core-platform.local pro external

# ✅ SPRÁVNĚ - Realm templates používají externí domény pro redirecty  
"frontendUrl": "https://admin.${DOMAIN}"
"redirectUris": ["https://admin.${DOMAIN}/*"]

# ❌ ŠPATNĚ - Míchat interní a externí!
KC_HOSTNAME: core-platform.local  # externí v interní konfiguraci

🔄 Workflow:

1. DNS: admin.core-platform.local → 127.0.0.1 (dnsmasq)
2. Nginx: Zachytí external request na port 443
3. Routing: admin.core-platform.local/realms/* → keycloak:8443/realms/*
4. Keycloak: Vrací response s correct external URLs
5. Browser: Redirecty používají external domény

---

🚀 S1-S9 Modernization Summary

Core Platform prošla kompletní 9-fázovou modernizací (říjen 2024 - říjen 2025) s následujícími výsledky:

📊 Overall Achievements

Metrika	Před S1-S9	Po S1-S9	Změna
Test Success Rate	0% (17 failing)	100% (65 passing)	+100% ✅
Code Coverage (Line)	45%	80%	+35% ✅
Code Coverage (Branch)	N/A	70%	NEW ✅
Security CVEs (HIGH+)	Unknown	0	✅
OWASP Compliance	Unknown	95.5%	✅
Developer Onboarding	2-3 dny	1-2 hodiny	-75% ⚡
API Testing Time	Manual cURL	Swagger UI	-70% ⚡

🎯 Completed Phases

✅ S1: Test Recovery

• Cíl: Oprava všech 17 selhávajících testů
• Výsledek: 100% test success rate, 75% code coverage (exceeded 70% goal)
• Dokumentace: TESTING.md, TEST_IMPLEMENTATION_SUMMARY.md

✅ S2: Presence NRT Tests

• Cíl: Near-real-time presence tracking tests
• Výsledek: Included in S1, 100% coverage for presence features

✅ S3: Naming-lint CI/CD

• Cíl: Enforce naming conventions across codebase
• Výsledek: 4 linters (Checkstyle, PMD, ESLint, Prettier) + Lefthook + GitHub Actions
• Features: Auto-formatting pre-commit hooks, CI quality gates

✅ S4: Entity-view SDK

• Cíl: Centralize entity management hooks
• Výsledek: -80% code duplication, enhanced React hooks, ESLint enforcement

✅ S5: Preagg-worker

• Cíl: Automated Cube.js pre-aggregation refresh
• Výsledek: 8/8 tests passing, 30s debounce, Kafka-driven workflow
• Dokumentace: REPORTING_IMPLEMENTATION_PROGRESS.md

✅ S6: Modelgen

• Cíl: Automated Cube.js schema generation from YAML
• Výsledek: 6/6 tests passing, YAML → JavaScript, +80% developer productivity
• Dokumentace: REPORTING_README.md

✅ S7: Streaming Revamp (3 phases)

• Cíl: Production-ready Kafka streaming with retry policies + DLT
• Výsledek: 9/9 tests passing, 99.9% consumer uptime
• Features:
  • Topic naming convention (tenant-specific topics)
  • Custom retry annotations (@CriticalRetry, @HighPriorityRetry, @NormalRetry, @BulkRetry)
  • Dead Letter Topic (DLT) Manager for failed messages
• Dokumentace: STREAMING_README.md, STREAMING_RUNBOOK.md

✅ S8: Platform Audit (6 phases)

• Cíl: Security scanning, code quality metrics, performance profiling
• Výsledek: 100% automated scanning, 80%/70% coverage thresholds
• Features:
  • OWASP Dependency-Check v11.1.0 (weekly scans, CVSS ≥ 7.0)
  • Dependabot (5 ecosystems: Maven, npm, Docker, GitHub Actions, Keycloak)
  • SpotBugs + PMD + Checkstyle (CI enforced)
  • JaCoCo enhanced: 80% line, 70% branch coverage
  • Performance metrics: JVM, Hibernate, HTTP, Kafka
• Dokumentace: SECURITY_RUNBOOK.md, PERFORMANCE_PROFILING.md

✅ S9: Documentation & Security (6 phases)

• Cíl: API documentation, OWASP compliance, troubleshooting guides
• Výsledek: 95.5% OWASP compliance, interactive Swagger UI
• Features:
  • Swagger UI: http://localhost:8080/swagger-ui.html (30+ endpoints)
  • OWASP Top 10 2021: Complete compliance checklist
  • Troubleshooting: 11 common issues with solutions
  • API Documentation: 500+ lines complete reference guide
• Dokumentace: API_DOCUMENTATION.md, OWASP_TOP_10_COMPLIANCE.md, TROUBLESHOOTING.md

🔐 Security & Quality

Automated Scanning:

• ✅ OWASP Dependency-Check (weekly + PR checks)
• ✅ Trivy container scanning
• ✅ GitLeaks secret detection
• ✅ SonarCloud static analysis
• ✅ SpotBugs + FindSecBugs (400+ bug patterns)
• ✅ PMD (code smells, complexity, duplication)
• ✅ Checkstyle (Google Java Style, 120 char limit)

Coverage & Quality Gates:

• ✅ JaCoCo: 80% line coverage (↑ from 70%), 70% branch coverage
• ✅ CI/CD: All quality checks enforced in PRs
• ✅ Pre-commit hooks: Auto-lint, auto-format via Lefthook

OWASP Top 10 2021 Compliance:

Category	Compliance	Controls
A01: Broken Access Control	100%	Multi-tenant isolation, RBAC, CORS
A02: Cryptographic Failures	95%	TLS 1.2+, bcrypt, RS256 JWT
A03: Injection	100%	JPA parameterized queries
A04: Insecure Design	100%	Threat modeling, secure defaults
A05: Security Misconfiguration	75%	Security headers, hardened containers
A06: Vulnerable Components	100%	OWASP + Dependabot automation
A07: Auth Failures	100%	Keycloak, MFA, brute force protection
A08: Integrity Failures	100%	Flyway checksums, dependency signing
A09: Logging Failures	100%	Loki + Grafana, security events
A10: SSRF	90%	URL validation, network segmentation
Overall	95.5%	40+ security controls

📚 API Documentation

Interactive Swagger UI:

http://localhost:8080/swagger-ui.html

API Categories:

• 👥 User Management (10 endpoints): CRUD, roles, password reset
• 🏢 Tenant Management (5 endpoints): Multi-tenancy admin
• 🔐 Role Management (7 endpoints): RBAC configuration
• 📊 Cube.js Analytics (5 endpoints): Model generation, pre-agg refresh
• 📈 Grafana Integration (proxy endpoints): Multi-tenant dashboards
• 🔄 Presence Tracking (3 endpoints): Real-time user activity

Authentication:

# Get JWT token from Keycloak
curl -X POST https://admin.core-platform.local/realms/admin/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=backend" \
  -d "username=admin@test.com" \
  -d "password=admin"

# Use in API calls
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/users

📊 Performance Monitoring

JVM Metrics (Micrometer):

• Memory: Heap/non-heap pools, usage %
• GC: Count, duration, overhead (target p99 <100ms)
• Threads: Live, peak, daemon, states
• Classes: Loaded, unloaded

Hibernate Statistics:

• Query execution time (slow query log >100ms)
• Query count, cache hit ratio
• N+1 detection

Custom Metrics:

• HTTP latency: p95 <200ms, p99 <500ms
• Kafka consumer lag: <100 messages
• Database query time: avg <50ms
• Cube.js pre-agg refresh duration

Access Points:

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000
• Actuator: http://localhost:8080/actuator/metrics

🛠️ Troubleshooting

Quick Health Check:

# All services status
docker ps --filter "name=core-platform" --format "table {{.Names}}\t{{.Status}}"

# Backend health
curl http://localhost:8080/actuator/health | jq

# Database check
docker exec core-platform-db-1 pg_isready -U core

Common Issues:

1. Backend won't start → Check Keycloak/DB readiness, Flyway migrations
2. 401 Unauthorized → JWT issuer/audience mismatch, token expiration
3. 403 Forbidden → Missing roles, role mapper configuration
4. Connection pool exhausted → Increase HikariCP pool size, check slow queries
5. Kafka consumer lag → Increase concurrency, batch size, check blocking calls

Full Guide: TROUBLESHOOTING.md (11 scenarios)

📖 Complete Documentation Index

Core Docs:

1. README.md - Project overview (this file)
2. MODERNIZATION_SUMMARY.md - Complete S1-S9 overview

API & Security (S9): 3. API_DOCUMENTATION.md - Swagger UI guide, cURL examples 4. OWASP_TOP_10_COMPLIANCE.md - Security checklist 5. TROUBLESHOOTING.md - Common issues & solutions

Security & Quality (S8): 6. SECURITY_RUNBOOK.md - CVE response, incident handling 7. PERFORMANCE_PROFILING.md - JVM/DB profiling guide

Streaming & Analytics (S5-S7): 8. STREAMING_README.md - Kafka architecture 9. STREAMING_RUNBOOK.md - Operations guide 10. REPORTING_README.md - Cube.js integration

Testing (S1-S2): 11. TESTING.md - Test strategy & results 12. TESTING_STRUCTURE.md - Complete testing guide 13. TESTING_FAQ.md - Testing FAQ (tests location, URLs, clean) 14. E2E_MAKEFILE_INTEGRATION.md - E2E integration guide 15. e2e/README.md - Playwright E2E setup

Development: 16. LOKI_MONITORING_UI.md - Native Loki UI user guide ⭐ 17. GRAFANA_OPS_ACCESS.md - Standalone Grafana for ops ⭐ NEW 18. DATABASE_MIGRATIONS_GUIDE.md - Flyway workflows

Total: 15,000+ lines of documentation across 40+ files

🎯 Next Steps: S10 - Production Hardening

Planned Features:

• Kubernetes deployment manifests (Deployments, Services, Ingress)
• Helm charts for templated deployments
• High availability (multi-replica, autoscaling, PVCs)
• SSL/TLS automation (cert-manager + Let's Encrypt)
• Production monitoring (Prometheus Operator, alerting rules)
• Disaster recovery (backup/restore, RTO/RPO)
• Load testing & capacity planning

---