# Nature In Pots Community Site

![License](https://img.shields.io/badge/license-MIT-blue) ![Flask](https://img.shields.io/badge/Flask-2.2-green) ![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-1.4-blue) ![Neo4j](https://img.shields.io/badge/Neo4j-5.0-yellow)

A modular, plugin-driven platform for tracking plants, propagation lineage, growth logs, pricing, and community submissions—built with Flask, MySQL, and Neo4j.

---

## 📌 Table of Contents

1. [Introduction & Goals](#introduction--goals)
2. [Architecture & Tech Stack](#architecture--tech-stack)
3. [Quickstart & Installation](#quickstart--installation)
4. [Project Structure](#project-structure)
5. [Core Features](#core-features)

   1. [Plant Profiles](#plant-profiles)
   2. [Grow Logs](#grow-logs)
   3. [Verified Lineage Tracking](#verified-lineage-tracking)
   4. [Pricing Logic](#pricing-logic)
   5. [Substrate & Fertilizer Tracking](#substrate--fertilizer-tracking)
   6. [Shipping Tracker](#shipping-tracker)
   7. [Plant Folders](#plant-folders)
   8. [Media Gallery & Voting](#media-gallery--voting)
   9. [QR & Barcode Labeling](#qr--barcode-labeling)
   10. [Offline Sync (PWA)](#offline-sync-pwa)
   11. [Smart Tools](#smart-tools)
6. [Plugin Ecosystem](#plugin-ecosystem)
7. [Data Models & Schema](#data-models--schema)
8. [APIs & CLI](#apis--cli)
9. [User Interface & PWA](#user-interface--pwa)
10. [Security & Privacy](#security--privacy)
11. [Permissions Matrix](#permissions-matrix)
12. [Admin & Dev Tools](#admin--dev-tools)
13. [Internationalization](#internationalization)
14. [Roadmap & Future Enhancements](#roadmap--future-enhancements)
15. [Contributing](#contributing)
16. [License](#license)

---

## 📝 Introduction & Goals

Nature In Pots empowers hobbyists, breeders, and businesses to:

* **Create & manage** rich plant profiles (names, lineage, pricing, notes).
* **Track growth** via logs with metrics, health/pest events, and custom traits.
* **Visualize propagation** on a Neo4j-powered ancestry graph.
* **Upload & curate** images—community-voted, featured selections.
* **Handle secure transfers** of ownership, preserving full history and privacy.
* **Organize** plants into folders with shareable QR/back-barcodes.
* **Import & export** comprehensive CSV/ZIP bundles, including media.
* **Extend** via plugins: materials, ledger, inventory, vendor collectives, and more.

---

## 🏗 Architecture & Tech Stack

* **Backend**: Python 3.11, Flask 2+, Flask-Login, Flask-Migrate (Alembic)
* **ORM**: SQLAlchemy (MySQL) & Neo4j Bolt driver
* **Storage**: Local FS (`UPLOAD_FOLDER`), optional S3 sync
* **Frontend**: Bootstrap 5, responsive + PWA caching
* **QR/Barcode**: Pillow + qrcode, CODE-128 barcodes
* **Security**: End-to-End encryption with optional key escrow
* **Testing**: pytest + coverage; CI/CD via GitHub Actions
* **Containerization**: Docker & Docker Compose

---

## 🚀 Quickstart & Installation

1. **Clone**

   ```bash
   git clone https://github.com/yourorg/nip-community.git
   cd nip-community
   ```
2. **Virtualenv & Dependencies**

   ```bash
   python3 -m venv venv; source venv/bin/activate  
   pip install -r requirements.txt
   ```
3. **Env & Config**
   Copy `.env.example` → `.env`, set `FLASK_APP=app`, DB/Neo4j URLs, `SECRET_KEY`, `UPLOAD_FOLDER`.
4. **Migrations**

   ```bash
   flask db init  
   flask db migrate  
   flask db upgrade
   ```
5. **Run**

   ```bash
   flask run --reload
   ```

   Access [http://localhost:5000](http://localhost:5000)

---

## 📂 Project Structure

```
.
├── app/                   # Core app factory, auth, errors, Neo4j utils
├── plugins/               # Feature modules (plant, media, utility, etc.)
│   ├── plant/
│   ├── media/
│   ├── utility/
│   ├── growlog/
│   ├── submissions/
│   ├── vendor/
│   └── (future: materials, ledger, inventory, collective)
├── migrations/            # Alembic scripts
├── static/                # Global assets
├── templates/             # Shared base templates
├── tests/                 # pytest suite
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md              # ← this file
```

---

## ⭐ Core Features

### 🌱 Plant Profiles

* **Create/Edit** plants with:

  * UUID & custom slug
  * Plant type (seed, cutting, tissue culture, division, etc.)
  * Common & scientific names (with lookup/autocomplete)
  * Vendor, notes, active flag
  * Parent (`mother_uuid`) references
* **Detail page** shows metadata, lineage nav, QR links, folders.

### 📓 Grow Logs

* Timestamped logs with:

  * Size, leaf count, substrate mix, potting notes
  * Health/pest/disease events & treatments
  * Up to 5 images per log
* **Timeline** view on plant detail.

### 🔗 Verified Lineage Tracking

* **Neo4j** graph for parent→child relationships.
* Pending link requests: parent-owner approval required.
* Verified links get a badge; unverified shown in draft.

### 💰 Pricing Logic

* **Owner & admin** see full pricing history; others do not.
* On transfer, seller’s last price is retained but hidden; buyer sets new price.
* **Price records** tracked as `PriceHistory` entries.
* Visibility toggles: `public`, `unlisted`, `folder-only`.

### 🧪 Substrate & Fertilizer Tracking

* Define **mix recipes**: ingredient list with cost per unit.
* Auto-calculate total mix cost based on usage (e.g., ounces, cups).
* Reusable recipes attachable to grow logs.
* **Fertilizer schedules** logged and outcomes tracked.

### 📦 Shipping Tracker

* During sale, seller enters: carrier, tracking number, est. delivery.
* Transfer completes after buyer confirmation.
* Shipping events attached to ownership log.

### 📁 Plant Folders

* Organize plants into **named folders** (e.g., “For Sale”, “2025 Seedlings”).
* Each folder has its own QR code and slug:
  `https://domain.com/{username}/folder/{id}|{slug}`
* Folder visibility: `public`, `private`, `unlisted`.

### 🖼 Media Gallery & Voting

* **Upload**, rotate, delete images per plant/growlog.
* Per-user “heart” or “broken heart” voting.
* **Featured image** toggle via media plugin; batch fallback to top-voted.
* EXIF data stripped on upload.

### 📇 QR & Barcode Labeling

* **QR codes** (SVG & PNG) unique per plant/folder.
* **Barcode (CODE-128)** fallback; splits long data into stacked barcodes.
* Printable labels via dashboard.

### 📶 Offline Sync (PWA)

* Full form support offline (plants, logs, submissions).
* Sync queue when back online.
* QR/barcode generation deferred until server sync.

### 🤖 Smart Tools

* **Reputation System**: users rated by buyers (accuracy, responsiveness).
* “Trusted Grower” badge auto-granted.
* **Inter-Plant Comparison**: side-by-side charts of growth metrics or events.

---

## 🔌 Plugin Ecosystem

| Plugin          | Purpose                                       | Status     |
| --------------- | --------------------------------------------- | ---------- |
| **plant**       | Core plant CRUD & lineage                     | ✅ Live     |
| **media**       | Image storage, EXIF, voting, featured         | ✅ Live     |
| **utility**     | Import/Export CSV/ZIP, QR code generation     | ✅ Live     |
| **growlog**     | Growth logs & update images                   | ✅ Live     |
| **submissions** | Community submissions & voting                | ✅ Live     |
| **vendor**      | Vendor/collective profiles, membership, roles | ✅ Live     |
| **materials**   | Potting mixes, proprietary flags              | 🔜 Planned |
| **ledger**      | Cost logs, fees, tax, shipping                | 🔜 Planned |
| **inventory**   | Stock management, restock/depletion           | 🔜 Planned |
| **collective**  | Shared groups with RBAC                       | 🔜 Planned |

---

## 📊 Data Models & Schema

Refer to `/migrations/` for full schema. Key tables include:

* `users`, `roles`, `user_roles`
* `plant_common_name`, `plant_scientific_name`
* **`plant`**: FKs → common, scientific, owner, mother\_uuid, featured\_media
* `media`: FKs → plant\_id, growlog\_id, uploader
* `featured_image`
* `plant_update`, `update_image`
* `plant_ownership_log`, `transfer_request`
* `submission`, `submission_image`
* `health_event`, `trait`, lookup tables
* `vendor_profile`, `vendor_member`, `affiliation_request`, `claim_request`
* `listing`, `price_history`
* `inventory_item`, `restock_event`, `depletion_event`

---

## 🛠 APIs & CLI

* **REST**: `/api/v1/` CRUD, OpenAPI docs, JWT auth, rate limiting
* **GraphQL**: `/graphql` batched queries for plants + relations
* **CLI**:

  * `flask db {init,migrate,upgrade}`
  * `flask user create`
  * `flask plugin {install,list,enable}`
  * `flask preload-data`

---

## 🌐 User Interface & PWA

* **Bootstrap 5** responsive layouts
* **Desktop**: large gallery + thumbnail carousel
* **Mobile**: grid lightbox with pinch-zoom & close button
* Offline caching via service worker

---

## 🔒 Security & Privacy

* **End-to-End Encryption** for notes, logs, pricing
* **Key Escrow** (opt-in) vs **Maximum Privacy** (no escrow)
* **Blind Transfers**: admin can reassign without decryption
* **Audit Logs**: immutable record of all actions
* **Role-Based Access**: owner, group member, moderator, admin

---

## 🛂 Permissions Matrix

| Action                        | Owner | Group | Mod | Admin |
| ----------------------------- | :---: | :---: | :-: | :---: |
| Create/Edit own plants & logs |   ✅   |  ✅\*  |  ✅  |   ✅   |
| View public plants/logs       |   ✅   |   ✅   |  ✅  |   ✅   |
| Approve lineage & submissions |   ❌   |   ❌   |  ✅  |   ✅   |
| Manage vendors/collectives    |   ❌   |   ❌   |  ❌  |   ✅   |
| Transfer override (no-owner)  |   ❌   |   ❌   |  ❌  |   ✅   |
| Plugin management & settings  |   ❌   |   ❌   |  ❌  |   ✅   |

\* if granted by group manager

---

## ⚙ Admin & Dev Tools

* **Moderator Panel**: flag review, user notes, bans
* **Seed Data Generator**: sample users, plants, logs
* **Plugin CLI**: install/enable/disable plugins at runtime
* **ERD Viewer**: visualize database schema
* **Disaster Recovery**: SQL dump + file archive + JSON profiles

---

## 🌍 Internationalization

* **Flask-Babel** for translations
* Language switcher in UI
* Community-managed translation portal (admin toggle)

---

## 🛣 Roadmap & Future Enhancements

* AI-powered journal assistant & mutation detection
* Calendar reminders for watering, fertilizing
* Visual ERD generator tool in admin UI
* Live auction & escrow plugin
* Third-party webhook integrations (Zapier, Discord)

---

## 🧾 License & Contribution

This project is part of **Nature In Pots** under **High Thyme Ventures**.

Please contact the repository owner for collaboration, plugin submission, or access requests.

