Live: qnbs.github.io/CannaGuide-2025 · Docs: DeepWiki
AI-powered, offline-first Progressive Web App for cannabis cultivation management. Simulates the full lifecycle from seed selection through harvest using VPD-based environmental modeling, 776-strain library with genealogy tracking, multi-provider AI diagnostics, and comprehensive equipment planning -- all running 100% client-side with no backend.
- Project Overview
- Getting Started
- Monorepo Architecture
- PWA & Offline Infrastructure
- State Management & Data Persistence
- Plant Simulation Engine
- AI System
- Detailed Plant View & Tabs
- Strain Library & Genetics
- Equipment & Calculators
- Knowledge Base & AI Mentor
- Settings & Configuration
- CI/CD, Testing & Security
- Distribution & Deployment
- Roadmap
- Contributing
- Acknowledgments
- Deutsche Version
776 strains · 2672 tests · 130 services · 19 Redux slices + 9 Zustand stores · 28 hooks · 12 i18n namespaces · 9 themes · 24 CI workflows
| Category | Technology | Purpose |
|---|---|---|
| Runtime | React 19 + TypeScript (strict) | Zero any, exactOptionalPropertyTypes |
| Build | Vite 7 + vite-plugin-pwa | InjectManifest SW, fast HMR |
| State | Redux Toolkit 2 + Zustand 5 | 19 persisted slices + 9 transient stores |
| AI (Cloud) | Gemini, OpenAI, Claude, Grok | Multi-provider BYOK abstraction |
| AI (Local) | Transformers.js, WebLLM, TF.js, ONNX | 22 services, 8 ML models, 3-layer fallback |
| Styling | Tailwind CSS + Radix UI | 9 cannabis themes via CSS custom properties |
| Persistence | IndexedDB (dual-database) | Offline-first, no backend |
| i18n | i18next | EN/DE/ES/FR/NL, 12 namespaces |
| Security | DOMPurify 3, Web Crypto AES-256-GCM | XSS prevention, encrypted API keys |
| Testing | Vitest + Playwright | 2672 unit/E2E/component tests |
Deep-dive: Architecture · Dependency Graph · Accessibility
Prerequisites: Node.js 24+, pnpm 10+ (via Corepack)
corepack enable
pnpm install --frozen-lockfile
pnpm run dev # Vite dev server on localhost:5173
pnpm run build # Production build (all workspaces)
pnpm run test:run # 2672 tests (229 files), single run
pnpm run typecheck # tsc --noEmit (TS2719 filtered)
pnpm run lint # ESLint (flat config, 0 warnings)All commands: docs/release-process.md · DevContainer: .devcontainer/
pnpm workspaces + TurboRepo with ML dependencies isolated in @cannaguide/ai-core.
apps/web/ Main PWA (@cannaguide/web)
components/ React components (common/, icons/, navigation/, ui/, views/)
stores/ Redux (19 slices) + Zustand (9 stores), selectors, middleware
services/ 130 service modules (AI, simulation, DB, crypto, IoT)
hooks/ 28 custom hooks
data/ Static data: 776 strains, FAQ, lexicon (91), guides, diseases (22)
locales/ i18n: en/, de/, es/, fr/, nl/ (12 namespaces each)
workers/ 11 Web Workers (VPD, genealogy, scenarios, inference, image gen,
hydro forecast, terpene, vision inference, calculation, voice, VPD sim)
packages/ai-core/ Shared AI types, provider configs, ML isolation (optionalDeps)
packages/ui/ Shared design tokens (9 themes) + Tailwind preset
scripts/ Build/lint/security/merge scripts
docker/ IoT mock servers (ESP32 sensor simulator)
Details: Monorepo Architecture · Architecture Migration Plan
| Feature | Implementation |
|---|---|
| Service Worker | Network-First navigation, Cache-First assets, InjectManifest via vite-plugin-pwa |
| Background Sync | Offline action queue in IndexedDB, replayed via sync event across all tabs |
| Dual IndexedDB | CannaGuideStateDB (Redux state, debounce-save 1s, force-save on visibilitychange) + CannaGuideDB (strains, images, full-text search) |
| Safe Recovery | Corrupted state auto-clear + restart with session flag to prevent loops |
| CRDT Sync | Yjs-powered conflict-free replication with encrypted GitHub Gists, 3-way conflict resolution UI |
| Store | Purpose | Persistence |
|---|---|---|
| Redux Toolkit (19 slices) | Simulation, settings, strains, favorites, notes, archives, breeding, genealogy, grows, problemTracker, metrics, diagnosis, planner, hydro, nutrients, sandbox, knowledge, savedItems, workerMetrics | IndexedDB (CannaGuideStateDB) |
| Zustand (9 stores) | UI, TTS, voice, filters, strains view, IoT, sensors, alerts, calculator session | Transient (never persisted) |
| RTK Query | AI API caching (9 endpoints) | In-memory |
Bridge: uiStateBridge.ts syncs Redux <-> Zustand via getReduxSnapshot, subscribeToRedux, dispatchToRedux.
- VPD Modeling: Transpiration simulation, biomass growth curves, environmental monitoring via Web Worker (
simulation.worker.ts) - IoT Integration: ESP32 sensors via MQTT/BLE, sparkline gauges, real-time telemetry (IoT Roadmap)
- WorkerBus: Centralized promise-based dispatcher for 11 workers with priority queue, backpressure, retry, AbortController, Transferable zero-copy, telemetry (Worker Bus Docs)
All calls route through aiFacade.ts -> aiService.ts -> aiProviderService.ts. Rate-limited (15 req/min). Structured JSON via Zod-validated responseSchema.
| Provider | Models | Service |
|---|---|---|
| Google Gemini | Primary | aiProviderService.ts |
| OpenAI | GPT series | aiProviderService.ts |
| Anthropic | Claude series | aiProviderService.ts |
| xAI | Grok series | aiProviderService.ts |
3-layer fallback: WebLLM -> Transformers.js -> Heuristics. All orchestrated via localAI.ts facade.
| Service | Purpose |
|---|---|
localAIModelLoader.ts |
ONNX backend detection, pipeline loading (max 3 concurrent) |
localAiNlpService.ts |
Sentiment, summarization, zero-shot classification |
localAiEmbeddingService.ts |
MiniLM-L6 embeddings, semantic ranking |
localAiDiagnosisService.ts |
Plant health diagnosis pipeline (ONNX classifiers) |
localAiWebLlmService.ts |
WebLLM lifecycle (Qwen2.5, Llama-3.2, Phi-3.5) |
localAiImageSimilarityService.ts |
CLIP feature extraction, growth tracking |
localAiFallbackService.ts |
Heuristic fallback when models unavailable |
localAiCacheService.ts |
IndexedDB inference cache (256 entries, 7d TTL) |
growLogRagService: Token-based journal search with dynamic top-K and sliding windowsanitizeForPrompt: 30+ regex patterns block injection (SQL, XSS, command, jailbreak)- EXIF/GPS stripping before image AI transmission
API docs: AI Facade · RAG Pipeline · Local AI Infrastructure
| Tab | Features |
|---|---|
| Dashboard | Lifecycle stages, VPD zone map, environmental gauges, proactive smart coach alerts |
| Journal | Grow log entries, photo timeline, compare mode, voice dictation |
| Metrics | Multi-metric Recharts charts (height, CO2, VPD), quick log form |
| AI Diagnosis | Vision AI leaf diagnosis (ONNX MobileNetV2, 38 classes), nutrient deficiency wizard (8-node decision tree), severity scoring |
| Tags | QR code plant tag generator with Print/PDF export |
| 3D Room | Three.js OrbitControls equipment placement and grow space planning |
| Reports | jsPDF grow reports with canvas-rendered charts, diagnosis history, AI summaries |
Multi-grow management: up to 3 independent grows per German CanG compliance.
| Feature | Details |
|---|---|
| Catalog | 776 strains, full-text search, filtering by type/effects/THC/CBD/terpenes |
| Profiles | 27 terpenes, 11 cannabinoids, chemovar classification (Type I-V), 12 flavonoids |
| Genealogy | D3.js parent-child lineage explorer, breeding lab cross predictions |
| Daily Drop | 5 seeded-PRNG daily picks with 7 diversity categories and match scoring |
| Intelligence | 5-source cascade lookup with entourage effect science context |
| Trends | Genetics 2026 hub: terpene diversity, autoflowering, polyploidy, landrace revival |
| Sharing | Community strain sharing via anonymous GitHub Gists |
| Feature | Details |
|---|---|
| Configurator | AI-recommended setups based on grow parameters, shopping list generation |
| Calculator Suite | Ventilation (CFM), lighting (PPFD/DLI), nutrients, pot sizing, CO2, humidity deficit (Buck SVP), light hanging height |
| Hydro Monitor | Real-time pH/EC/Temp dashboard with ONNX forecast (off-thread worker, moving-average fallback) |
| IoT Dashboard | ESP32 MQTT/BLE sensors, sparkline gauges, real-time telemetry |
| What-If Sandbox | Breeding and scenario simulations with grow-parameter exploration |
| Seedbanks | Deterministic mock pricing, 5 hardcoded seedbanks |
| Feature | Details |
|---|---|
| AI Mentor | RAG chat pulling context from user's grow journals, streaming responses |
| Lexikon | 91-term searchable glossary across 6 categories (General, Cannabinoid, Terpene, Flavonoid, Nutrient, Disease) |
| Disease Atlas | 22-entry diagnostic reference (deficiencies, toxicities, pests, diseases) with urgency classification |
| Calculator Hub | VPD, Nutrient Ratio, pH/EC calculators in unified tabbed view |
| Learning Paths | 5 step-by-step programs (Beginner, Environment, Nutrients, Pests, Advanced) with Redux-tracked progress |
| Analytics | Grow performance dashboard with AI-recommended optimizations |
| Feature | Details |
|---|---|
| Themes | 9 cannabis themes, 3 colorblind modes (deuteranopia, protanopia, tritanopia) |
| BYOK | AES-256-GCM encrypted API key management, 90-day rotation, cost tracking |
| WebLLM | Card-based model selector (Qwen2.5-0.5B/1.5B, Llama-3.2-3B, Phi-3.5-mini), GPU-tier auto-selection |
| Voice | 37 voice commands, Porcupine wake-word, ElevenLabs Cloud TTS, Voice HUD, continuous listening |
| CRDT Sync | Yjs + encrypted GitHub Gists, 3-way conflict resolution, offline queue with exponential backoff |
| Data | JSON export/import, local-only mode toggle, TTS for AI responses |
| Grow Manager | Multi-grow CRUD with archive, color picker, CanG compliance limits |
| Type | Framework | Scope |
|---|---|---|
| Unit/Integration | Vitest | 2672 tests, colocated *.test.ts(x) |
| E2E | Playwright | Chromium + Firefox (CI), tests/e2e/*.e2e.ts |
| Component | Playwright CT | tests/ct/*.ct.tsx |
| Mutation | Stryker | Redux slices, 50% break threshold |
| Visual Regression | Playwright | Theme screenshots, tests/e2e/__screenshots__/ |
| Fuzzing | ClusterFuzzLite | PR-triggered continuous fuzzing |
| Layer | Implementation |
|---|---|
| Input Sanitization | DOMPurify v3, ALLOWED_TAGS/ATTR |
| Prompt Injection | 30+ regex patterns (SQL, XSS, command, jailbreak) |
| API Key Encryption | AES-256-GCM via Web Crypto, 96-bit IV |
| CSP | 'self' 'unsafe-inline' 'wasm-unsafe-eval', no eval |
| EXIF Stripping | Canvas re-encode removes GPS/metadata |
| SAST | CodeQL, Grype, Semgrep, Gitleaks, trojan-source |
| Supply Chain | GitHub build attestation, CycloneDX SBOM, SHA-pinned actions |
| Access Gates | Age verification (KCanG), PIN lock, DSGVO consent |
Details: SECURITY.md · Audit Backlog
| Workflow | Trigger | Purpose |
|---|---|---|
| CI | push, PR | Lint, typecheck, 2672 tests, build, security, E2E, IoT |
| CodeQL | push, PR, weekly | SAST (JavaScript/TypeScript) |
| Deploy | push to main | GitHub Pages + Lighthouse budget gate |
| Release Publish | tag v* | GitHub build attestation + CycloneDX SBOM + GitHub Release |
| Release Gate | tag v* | Pre-release quality gate (typecheck, tests, build, audit) |
| Security Full | push, PR, weekly | Comprehensive security scan suite |
| Snyk | push, PR | Vulnerability scanning |
| ClusterFuzzLite | PR | Continuous fuzzing |
| Scorecard | push, weekly | OpenSSF Scorecard |
| Config Guard | push, PR | RCE pattern scanning in configs |
| Mutation Testing | push, PR | Stryker Redux slice mutation testing |
| Preview Validation | deploy | Playwright + Lighthouse on deploy previews (paused) |
| + 12 more | various | Benchmarks, strains, Dependabot, labeler, stale, cleanup, Cloudflare deploy |
| Target | Method | URL / Config |
|---|---|---|
| GitHub Pages | deploy.yml on push to main |
qnbs.github.io/CannaGuide-2025 |
| Vercel | vercel.json, Git integration |
Connect via Vercel Dashboard |
| Cloudflare Pages | _headers + _redirects, Git |
Connect via Cloudflare Dashboard |
netlify.toml |
PAUSED until v2.0 (bandwidth limit) |
Details: Distribution · Release Process
| Version | Status | Highlights |
|---|---|---|
| v1.0 | Released | 776 strains, VPD simulation, multi-provider AI, DSGVO/WCAG, ESP32 |
| v1.1 | Released | Local AI stack (WebLLM + Transformers.js + CLIP), Sentry, cloud sync |
| v1.2 | Released | Terpene profiles (27), chemovar, flavonoids (12), ES/FR/NL, WorkerBus |
| v1.3 | Released | IoT dashboard, 3D OrbitControls, strain recommendation, Knowledge suite |
| v1.4 | Released | Vision AI Leaf Diagnosis, Hydro Forecast, WebLLM Catalog, Multi-Grow |
| v1.5 | Released | CRDT sync, AI cost tracking, preview validation, pnpm migration |
| v1.6 | Released | Forensic audit, i18n completeness, metrics/diagnosis/planner slices, build attestation |
| v1.7 | Released | Voice Pro (wake-word, Cloud TTS), 12 Preset Setups, Enhanced PDF, a11y |
| v1.8 | Released | HydroMonitor, Predictive Analytics, Glassmorphism, Worker Pool W-06 |
| v2.0 | Planned | AR/VR plant overlay, digital twin architecture, next-gen Sandbox/BreedingLab |
Full roadmap: ROADMAP.md · Priority Roadmap · Audit Backlog · ADRs · Session Handoff · UX Audit · Lint Burndown · Worker Bus
Contributions welcome! See CONTRIBUTING.md for guidelines. API reference: docs/api/.
- Open an issue to discuss
- Fork -> branch -> commit -> push -> PR
- Follow Conventional Commits:
<type>(<scope>): <description>
AI & ML: Google Gemini API, OpenAI API, Anthropic API, xAI/Grok API, Hugging Face Transformers.js, MLC WebLLM, TensorFlow.js, ONNX Runtime Web · Strain Data: AI-assisted research (Gemini, Opus) based on publicly available breeder/seedbank/community information · Frontend: React, Vite, Tailwind CSS, Radix UI, Recharts, D3.js, i18next, Zod, Redux Toolkit, Zustand · Security: DOMPurify, Sentry, Semgrep, Gitleaks, Grype, Snyk, CodeQL, ClusterFuzzLite, OpenSSF Scorecard · Infrastructure: GitHub Pages, Vercel, Cloudflare Pages, TurboRepo · Icons: Phosphor Icons
| Phase | Tools | Period |
|---|---|---|
| Prototyping | Google AI Studio (Gemini 2.5 Pro & 3.1 Pro) | v0.1 -> v1.0 |
| Evaluation & Advisory | xAI Grok 4.20 | Throughout |
| Core Development | GitHub Codespaces + VS Code Copilot (Claude Opus 4.6) | v1.0 -> v1.7 |
| Deployment | GitHub Pages, Vercel, Cloudflare Pages | Continuous |
Secondary contributions: GPT-4 Mini and GPT-5.3 Codex provided minimal supplementary assistance.
All information in this app is for educational and entertainment purposes only. Cannabis cultivation is subject to strict regulations. Please check the laws in your region and always act responsibly and legally. This app does not provide legal or medical advice.
Live: qnbs.github.io/CannaGuide-2025 · Doku: DeepWiki
KI-gestuetzte, offline-first Progressive Web App fuer Cannabis-Anbau-Management. Simuliert den kompletten Lebenszyklus von der Sortenauswahl bis zur Ernte mit VPD-basierter Umgebungsmodellierung, 776-Sorten-Bibliothek mit Genealogie-Tracking, Multi-Provider KI-Diagnostik und umfassender Ausruestungsplanung -- alles 100% clientseitig ohne Backend.
776 Sorten · 2672 Tests · 130 Services · 19 Redux Slices + 9 Zustand Stores · 28 Hooks · 12 i18n-Namensraeume · 9 Themes · 24 CI-Workflows
| Kategorie | Technologie | Zweck |
|---|---|---|
| Runtime | React 19 + TypeScript (strict) | Null any, exactOptionalPropertyTypes |
| Build | Vite 7 + vite-plugin-pwa | InjectManifest SW, schnelles HMR |
| State | Redux Toolkit 2 + Zustand 5 | 19 persistierte Slices + 9 transiente Stores |
| KI (Cloud) | Gemini, OpenAI, Claude, Grok | Multi-Provider BYOK-Abstraktion |
| KI (Lokal) | Transformers.js, WebLLM, TF.js, ONNX | 22 Services, 8 ML-Modelle, 3-Schicht-Fallback |
| Styling | Tailwind CSS + Radix UI | 9 Cannabis-Themes via CSS Custom Properties |
| Persistenz | IndexedDB (Dual-Datenbank) | Offline-first, kein Backend |
| i18n | i18next | EN/DE/ES/FR/NL, 12 Namensraeume |
| Sicherheit | DOMPurify 3, Web Crypto AES-256-GCM | XSS-Praevention, verschluesselte API-Keys |
| Testing | Vitest + Playwright | 2672 Unit-/E2E-/Komponenten-Tests |
Architektur: ARCHITECTURE.md · Dependency Graph · Barrierefreiheit
corepack enable
pnpm install --frozen-lockfile
pnpm run dev # Vite Dev-Server auf localhost:5173
pnpm run build # Produktions-Build
pnpm run test:run # 2672 Tests (229 Dateien), Einzellauf
pnpm run typecheck # tsc --noEmit| Modul | Highlights |
|---|---|
| Pflanzen | VPD-Simulation, Vision-KI Blattdiagnose (ONNX, 38 Klassen), Naehrstoffmangel-Wizard, Proaktiver Smart Coach, 3D Grow Room, Multi-Grow (3 pro CanG), PDF-Reports |
| Sorten | 776 Sorten, D3.js Genealogie-Explorer, 27 Terpene, 11 Cannabinoide, Chemovar (Typ I-V), 4:20 Daily Drop, Sorten-Intelligenz (5-Quellen-Kaskade) |
| Ausruestung | KI-Konfigurator, Rechner-Suite (CFM/PPFD/DLI/CO2/pH/EC), Hydro-Monitor + ONNX-Forecast, IoT-Dashboard (ESP32), What-If-Sandbox |
| Wissen | KI-Mentor mit RAG, Lexikon (91 Begriffe), Krankheits-Atlas (22 Eintraege), Rechner-Hub, 5 Lernpfade, Analyse-Dashboard |
| Einstellungen | 9 Themes + 3 Farbenblind-Modi, BYOK (AES-256-GCM), WebLLM-Modellauswahl, 37 Sprachbefehle, CRDT Cloud-Sync, Grow-Manager |
| Hilfe | Benutzerhandbuch (7), Lexikon (91), Visuelle Guides (4), FAQ (45) -- 138 Hilfe-Eintraege gesamt |
| Schicht | Details |
|---|---|
| Cloud (BYOK) | 4 Provider (Gemini, OpenAI, Claude, Grok), 15 Req/Min Rate-Limit, Zod-validiert |
| Lokal (22 Services) | WebLLM -> Transformers.js -> Heuristiken (3-Schicht-Fallback) |
| RAG | Token-basierte Journal-Suche, dynamisches Top-K, Sliding-Window-Retrieval |
| Sicherheit | 30+ Regex-Injection-Filter, EXIF-Stripping, DOMPurify-Sanitisierung |
API-Doku: AI Facade · RAG Pipeline · Local AI
| Bereich | Details |
|---|---|
| Tests | 2290 (Vitest + Playwright E2E + Komponenten + Stryker Mutation + Visual Regression + Fuzzing) |
| Sicherheit | DOMPurify, 30+ Prompt-Injection-Filter, AES-256-GCM, gehaertete CSP, GitHub Attestation, CycloneDX SBOM |
| CI/CD | 22 Workflows, CodeQL, Grype, Snyk, Semgrep, Gitleaks, ClusterFuzzLite, OpenSSF Scorecard |
| Supply Chain | GitHub Build Attestation + CycloneDX SBOM + SHA-gepinnte Actions + Allowlist |
| Distribution | GitHub Pages (Push auf main), Vercel, Cloudflare Pages |
Details: SECURITY.md · Audit-Backlog · Release-Prozess
| Version | Status | Highlights |
|---|---|---|
| v1.0-v1.7 | Veroeffentlicht | 776 Sorten, VPD, Multi-Provider KI, lokaler KI-Stack, CRDT-Sync, Build Attestation, Voice Pro |
| v2.0 | Geplant | AR/VR-Pflanzenoverlay, Digital-Twin-Architektur, naechste Sandbox/BreedingLab-Generation |
Vollstaendige Roadmap: ROADMAP.md · Priority Roadmap · Session-Handoff
Beitraege willkommen! Siehe CONTRIBUTING.md. API-Referenz: docs/api/.
Alle Informationen in dieser App dienen ausschliesslich zu Bildungs- und Unterhaltungszwecken. Der Anbau von Cannabis unterliegt strengen gesetzlichen Bestimmungen. Bitte informieren Sie sich ueber die Gesetze in Ihrer Region und handeln Sie stets verantwortungsbewusst und im Einklang mit dem Gesetz. Diese App bietet keine Rechts- oder Medizinberatung.