01 - Systemübersicht & Architektur
Dokument: Technische Systemübersicht
Stand: 28.02.2026
Scope: Mobile App (/app)
Status: Audit-ready
1. Systemüberblick
Die ChainBETs Mobile App ist eine Blockchain-basierte Lotterieplattform auf Arbitrum (L2). Nutzer kaufen Lotterietickets in verschiedenen Preispools, wobei alle Transaktionen über Smart Contracts abgewickelt werden. Bezahlung erfolgt in USDT (Tether, 6 Decimals), Zufallszahlen werden über Chainlink VRF generiert.
Kernfunktionen
- Lotterieticket-Kauf in 5 Preispools (0,25 - 10,00 USDT)
- Zahlenauswahl (6 aus 40) mit Quick-Pick-Option
- Bonus-Tip-System (ab 5 Tips automatische Gratistips)
- Gasless UX via Relayer (Nutzer zahlt kein ETH)
- Gewinn-Claiming über Merkle-Tree-basierte Proofs
- Affiliate-/Referral-Programm mit Provisionen
- Multi-Plattform: Web, Telegram Mini App, PWA
- KYC-Integration (Sumsub) mit Schwellenwert-basierter Verifizierung
2. Technologie-Stack
Frontend
| Technologie |
Version |
Zweck |
| Next.js |
16.1.1 |
App Router, SSR, API Routes |
| React |
19.2.3 |
UI-Rendering |
| TypeScript |
5.x |
Typsicherheit (strict mode) |
| Tailwind CSS |
4.1.18 |
Styling |
Blockchain & Web3
| Technologie |
Version |
Zweck |
| ethers.js |
6.16.0 |
Ethereum-Interaktionen, Signaturen |
| @web3auth/modal |
10.13.2 |
Wallet-Authentifizierung |
| @web3auth/ethereum-provider |
9.7.0 |
EVM Provider Plugin |
| @web3auth/base |
9.7.0 |
Basis-Typen & Konfiguration |
Backend & Datenbank
| Technologie |
Version |
Zweck |
| PostgreSQL (pg) |
8.17.2 |
Hauptdatenbank, max. 10 Connections |
| PostgreSQL (charity) |
- |
Separate Charity-DB, max. 5 Connections |
| Next.js API Routes |
- |
Server-seitige Endpoints (Pages Router) |
Zusätzliche Abhängigkeiten
| Technologie |
Version |
Zweck |
| next-intl |
4.8.2 |
Internationalisierung (EN/DE) |
| @telegram-apps/sdk-react |
3.3.9 |
Telegram Mini App Integration |
| react-qr-code |
2.0.18 |
QR-Code-Generierung (Referral) |
| canvas-confetti |
1.9.4 |
Gewinn-Animationen |
Laufzeitumgebung
| Parameter |
Wert |
| Development Port |
3001 |
| Build-System |
Next.js Built-in |
| Ziel-Netzwerk |
Arbitrum Sepolia (Chain ID: 421614) |
| RPC Provider |
Alchemy |
3. Projektstruktur
app/
├── app/ # Next.js App Router
│ ├── layout.tsx # Root Layout (PWA, Telegram SDK)
│ ├── globals.css # Global Styles
│ ├── [locale]/ # Lokalisierte Seiten (EN/DE)
│ │ ├── layout.tsx # Provider-Stack
│ │ ├── page.tsx # Login / Marketing
│ │ ├── play/page.tsx # Spielseite
│ │ ├── dashboard/page.tsx # Benutzer-Dashboard (3.331 Zeilen)
│ │ ├── account/page.tsx # Kontoverwaltung (2.771 Zeilen)
│ │ ├── claim/page.tsx # Gewinn-Claiming (953 Zeilen)
│ │ ├── global-stats/page.tsx # Plattform-Statistiken (1.258 Zeilen)
│ │ ├── how-it-works/page.tsx # Spielregeln (1.053 Zeilen)
│ │ ├── charity/page.tsx # Charity Voting (506 Zeilen)
│ │ ├── terms/page.tsx # AGB & Datenschutz
│ │ ├── welcome/page.tsx # Welcome/Landing
│ │ ├── tx/[hash]/page.tsx # Transaktionsdetails
│ │ └── account/revoke/page.tsx # Allowance widerrufen
│ ├── ref/[code]/page.tsx # Referral-Redirect
│ ├── api/email/view/route.ts # E-Mail View (App Router)
│ ├── components/ # 24 React-Komponenten
│ │ ├── website/ # 4 Marketing-Komponenten
│ │ └── index.ts # Barrel Export
│ ├── hooks/ # 10 Custom Hooks
│ └── providers/ # 2 Context Provider
├── pages/ # Next.js Pages Router (Legacy API)
│ └── api/ # 41 API-Endpunkte
│ ├── buy/ # 7 Ticket-Kauf-Endpoints
│ ├── claim/ # 4 Claim-Endpoints
│ ├── user/ # 6 Benutzer-Endpoints
│ ├── player/ # 1 Player-Init
│ ├── admin/ # 4 Admin-Endpoints
│ ├── kyc/ # 2 KYC-Endpoints
│ ├── push/ # 2 Push-Endpoints
│ ├── telegram/ # 1 Webhook
│ ├── charity/ # 2 Charity-Endpoints
│ └── [root-level] # 8 weitere Endpoints
├── lib/ # 14 Utility-Dateien
├── types/ # TypeScript-Definitionen
├── i18n/ # i18n-Konfiguration
├── messages/ # Übersetzungsdateien (EN/DE)
├── public/ # Static Assets (21 Dateien)
│ ├── manifest.json # PWA-Manifest
│ └── sw.js # Service Worker
├── .env # Umgebungsvariablen (125+)
├── proxy.ts # Request-Proxy & Route-Whitelist
├── next.config.ts # Next.js Config
├── tsconfig.json # TypeScript Config
└── package.json # Dependencies
4. Provider-Hierarchie
RootLayout
├── Telegram SDK Script (telegram-web-app.js)
├── PWA Metadata (manifest.json)
└── LocaleLayout
├── NextIntlClientProvider (i18n)
└── TelegramProvider (Telegram-Erkennung)
└── Web3AuthProvider (Wallet & Auth, 1.152 Zeilen)
└── DeviceProvider (Gerätetyp)
├── OfflineBanner
├── MaintenanceBanner
├── NotificationQueue
├── {children} (Seiteninhalte)
├── ProfileIncompleteModal
├── WinCongratulationRegistrar
├── BonusNotification
└── YesterdayWinnersRegistrar
5. Request-Proxy (proxy.ts)
Alle eingehenden Requests durchlaufen einen Sicherheits-Proxy:
Funktionsweise
| Schritt |
Beschreibung |
| Route-Matching |
Request wird gegen Whitelist geprüft |
| Locale-Erkennung |
URL-Pfad > Cookie (NEXT_LOCALE) > Accept-Language > Default (en) |
| API-Schutz |
Unbekannte API-Routes geben 404 zurück |
| Seiten-Schutz |
Unbekannte Seiten-Routes werden zu / redirected |
| Static Files |
Favicon, Manifest, SW, Icons werden durchgelassen |
Whitelist-Kategorien
- Seiten: 14 erlaubte Routen (inkl. dynamische wie
/tx/*, /ref/*)
- API-Endpunkte: 30+ exakte Matches + 10 Prefix-Patterns
- Static Files: Favicon, Manifest, Service Worker, Icons
6. Datenbank-Architektur
Hauptdatenbank (chainbets)
| Parameter |
Wert |
| System |
PostgreSQL |
| Max Connections |
10 |
| Host |
Konfiguriert via DB_HOST |
Charity-Datenbank (chainbets_charity)
| Parameter |
Wert |
| System |
PostgreSQL |
| Max Connections |
5 |
| Zweck |
Charity Voting System |
Read-Only Replica
- Konfiguriert via
DATABASE_URL_RO
- Verwendet für Claim-Payload-Abfragen
7. Kennzahlen
| Metrik |
Wert |
| Source Files (gesamt) |
~126 |
| UI-Komponenten |
28 (24 + 4 Website) |
| Custom Hooks |
10 |
| API-Endpunkte |
41 |
| Seiten/Routes |
14 |
| Context Provider |
3 (Web3Auth, Telegram, Device) |
| Utility-Module |
14 |
| Sprachen |
2 (EN, DE) |
| Umgebungsvariablen |
125+ |
| Smart Contracts integriert |
10+ |
| Programmiersprache |
100% TypeScript (strict mode) |
Weiterführende Dokumente:
- 02 - Authentifizierung
- 03 - Seitenstruktur
- 08 - Blockchain
- 15 - Konfiguration