pi_mcps/plans/cannabis-club-saas/docs/README.md

CannaManage 🌿

B2B compliance and membership management SaaS for German cannabis social clubs (Cannabis-Anbauvereine).

---

What is CannaManage?

Since April 2024, the Cannabisgesetz (CanG) permits licensed non-commercial social clubs to cultivate and distribute cannabis to their members. Each club must enforce strict distribution quotas, maintain tamper-proof audit logs, verify member eligibility, and comply with record-keeping obligations — all under threat of criminal liability for club officers.

CannaManage is a purpose-built SaaS platform that makes these compliance obligations manageable. Club administrators get a single interface to track membership, record distributions against per-member quotas (25g/day, 50g/month for adults; 30g/month for under-21 members), manage cannabis stock batches, and generate the distribution logs required during official inspections.

The platform is B2B only: it serves club administrators, not end consumers. It never stores member identities in a publicly discoverable way and contains no features that could be construed as advertising cannabis to the public — a legal requirement under CanG §§6–7. All data remains within the EU on Hetzner infrastructure.

---

Key Features (MVP)

• Member management — Registration, age verification (18+ required), under-21 flagging, status lifecycle (ACTIVE → SUSPENDED → EXPELLED)
• Distribution tracking — Real-time quota enforcement: 25g/day, 50g/month (adults), 30g/month (under-21), ≤10% THC for under-21 members
• Compliance audit log — Immutable distribution records; no UPDATE or DELETE on completed distributions
• Stock & batch management — Strain catalogue with THC/CBD percentages, batch tracking from intake to zero, batch recall with member notification
• Multi-tenancy — Full data isolation per club; shared-schema architecture with tenant_id filter
• PDF compliance reports — iText 7 generated distribution logs formatted for regulatory inspection
• Stripe billing integration — Subscription management per club; 4-tier pricing; webhook-driven provisioning
• Member self-service portal — Quota dashboard, personal distribution history, appointment booking
• Role-based access — ROLE_ADMIN (club officers), ROLE_MEMBER (read-only self-service)
• JWT authentication — Stateless API with short-lived access tokens and secure refresh token rotation

---

Tech Stack

Layer	Technology
Backend framework	Spring Boot 3.x (Java 21)
Persistence	Spring Data JPA / Hibernate 6
Database	PostgreSQL 16
Database migrations	Flyway
Frontend (MVP)	PrimeFaces 14 (JSF)
Frontend (v2 target)	Next.js 15 + React 19
PDF generation	iText 7
Billing	Stripe Java SDK
Email	Spring Mail (SMTP)
Error tracking	Sentry Java SDK
Containerization	Docker + Docker Compose
Infrastructure	Hetzner VPS (CX21, Ubuntu 22.04)
Reverse proxy	Nginx (TLS termination)
Build tool	Maven (multi-module)
Testing	JUnit 5, Mockito, Testcontainers
CI/CD	Gitea Actions

---

Architecture

See 03-ARCHITECTURE.md for the full system design, including:

• Maven multi-module structure (cannamanage-domain, cannamanage-service, cannamanage-api, cannamanage-web)
• JPA entity model (8 entities: Club, Member, Distribution, Strain, Batch, Subscription, PricingPlan, InspectionReport)
• Multi-tenancy implementation (shared schema with Hibernate filter)
• Security architecture (JWT + Spring Security)

---

Getting Started (Development Setup)

Prerequisites

• Java 21 (sdk install java 21.0.3-tem)
• Maven 3.9+
• Docker Desktop (for local PostgreSQL via Testcontainers or docker compose up db)
• Your preferred IDE (IntelliJ IDEA recommended for Spring Boot)

Local development

git clone http://192.168.188.119:30008/pplate/cannamanage.git
cd cannamanage

# Copy environment template
cp .env.example .env
# Edit .env — fill in DB credentials and JWT secret for local dev

# Start local PostgreSQL (Docker)
docker compose up db -d

# Run application (Flyway migrations run automatically)
./mvnw spring-boot:run -pl cannamanage-api

# Application available at:
# http://localhost:8080        — PrimeFaces UI
# http://localhost:8080/api/   — REST API
# http://localhost:8080/actuator/health — Health check

Running Tests

# Unit tests only (fast, no Docker required)
./mvnw test -pl cannamanage-service

# All tests including integration (requires Docker for Testcontainers)
./mvnw verify -P integration-tests

# Coverage report
./mvnw verify jacoco:report
# Open: cannamanage-service/target/site/jacoco/index.html

---

Documentation Index

#	Document	Description
01	01-PROJECT-CHARTER.md	Project scope, objectives, stakeholders, constraints
02	02-USER-STORIES.md	25 user stories across 5 epics with acceptance criteria
03	03-ARCHITECTURE.md	System design, data model, multi-tenancy, security
04	04-FLOWCHARTS.md	Distribution flow, member lifecycle, billing flow (Mermaid)
05	05-API-SPEC.md	REST API specification — 7 controllers, 30+ endpoints
06	06-WIREFRAMES.md	UI wireframes for 6 screens + AI-generated mockups
07	07-CODING-STANDARDS.md	Java coding conventions, compliance rules, JPA patterns
08	08-TEST-PLAN.md	Test strategy, 26 test cases, coverage requirements
09	09-DEPLOYMENT-GUIDE.md	Hetzner VPS deployment, CI/CD pipeline, backup
10	10-RETROSPECTIVE.md	Sprint 0 retrospective — planning phase review

---

Pricing

Four tiers targeting different club sizes:

Tier	Price	Members	Key inclusions
Starter	€29/month	Up to 50	Core compliance, basic reports
Growth	€59/month	Up to 150	+ PDF exports, email notifications
Professional	€99/month	Up to 500	+ Stripe billing, priority support
Enterprise	€199/month	Unlimited	+ Custom reports, API access, SLA

All tiers include a 30-day free trial. Annual billing available at 2 months free (×10/12 monthly rate).

Market sizing: Germany had approximately 3,000+ registered cannabis social clubs as of early 2026. At average Growth tier pricing, TAM is approximately €2.85M ARR.

---

Legal Notice

CannaManage operates exclusively as a B2B SaaS tool for licensed Cannabis-Anbauvereine registered under CanG (Cannabisgesetz, effective April 2024). Key legal positions:

• No public directory: CannaManage contains no feature that enables public discovery of clubs or their locations. Club data is never exposed publicly or to other clubs.
• No advertising: The platform does not advertise cannabis products to consumers. Club admins manage their own members — no public-facing cannabis content.
• CanG compliance: Quota limits (25g/day, 50g/month for adults; 30g/month for under-21 members; ≤10% THC for under-21) are hardcoded constants, not configurable per club. This prevents compliance from being accidentally disabled.
• GDPR: All data stored on EU infrastructure (Hetzner, Germany/Finland datacenters). Member personal data handled under GDPR legitimate interest basis (club membership) and statutory record-keeping obligation (CanG §26).
• Minimum age: Club membership and therefore access to the member portal requires age 18+, verified at registration.

CannaManage is a management tool, not a cannabis marketplace. Club officers remain personally responsible for their club's legal compliance under CanG.

---

Development Status

Phase 0 — Foundation (Planning) — ✅ Complete as of 2026-04-06

The complete documentation suite (10 documents) has been written, covering architecture, API specification, data model, wireframes, test plan, and deployment guide. No production code has been written yet.

Sprint 1 goals (next):

• Initialize Spring Boot 3.x Maven multi-module project
• Implement AbstractTenantEntity and Flyway baseline migration (V1__initial_schema.sql)
• Build ComplianceService with 100% test coverage (TC-001 through TC-010)
• Validate concept with 3 real club admins
• Obtain specialist legal opinion on CanG compliance approach

---

License

Proprietary — All Rights Reserved

Copyright © 2026 Patrick Plate. All rights reserved.

This software and all associated documentation are proprietary and confidential. No part of this codebase may be reproduced, distributed, or transmitted in any form without the prior written permission of the author.