327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
# Nature In Pots Community Site
|
||
|
||
   
|
||
|
||
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.
|
||
|