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

# CannaManage 🌿

![Status: Planning](https://img.shields.io/badge/Status-Planning-yellow)
![Stack: Spring Boot 3.x + PrimeFaces](https://img.shields.io/badge/Stack-Spring%20Boot%203.x%20%2B%20PrimeFaces-brightgreen)
![Legal: CanG-Compliant](https://img.shields.io/badge/Legal-%E2%9C%85%20CanG--Compliant-blue)
![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red)

**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`](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

```bash
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

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