lilfade/natureinpots_community
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

things

Browse Source
This commit is contained in:
Bryson Shepard
2025-06-27 17:43:50 -05:00
parent 00fd49c79b
commit 13d56066ab
22 changed files with 1500 additions and 497 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
README.md
View File

@ -1,179 +1,320 @@
# 🌿 Nature In Pots — Ultra Plant Tracker Platform
# Nature In Pots Community Site
> Modular, collaborative, end-to-end plant tracking and pricing platform with QR+barcode IDs, propagation logs, resale tools, and role-based management.
![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.
---
## 🧩 Overview
## 📌 Table of Contents
This is a full-feature, plugin-driven Flask 2+ web application for managing and tracking plant ownership, propagation, pricing, and growth. It supports dynamic plant attributes, collaboration groups, trade logs, QR/barcode labeling, resale workflows, offline sync, moderator tools, and future AI/ML modules.
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)
Built for hobbyists, businesses, breeders, and community gardens.
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)
---
## 🚀 Core Features
## 📝 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
- Add, edit, and log plants with full propagation and ownership history
- Each plant is assigned a permanent, scannable **QR code** and **barcode**
- Plants can be marked as `Public`, `Unlisted`, or `Folder-only`
- All pricing, logs, and lineage are tied to a plant ID and user
### 🧾 Grow Logs
- Add logs with images, notes, and growth metrics
- Track success/failure events, mutation events, pest/disease sightings
- Link logs to substrate recipes and fertilizers
* **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
- Lineage links are created by the new owner
- Parent plant's owner must **approve** the linkage
- Verified lineage is marked with a badge and shown in plant lineage tree
- Pending links are visible only to the creator
* **Neo4j** graph for parent→child relationships.
* Pending link requests: parent-owner approval required.
* Verified links get a badge; unverified shown in draft.
### 💰 Pricing Logic
- Only the current owner and admins can see pricing
- On transfer, original price is retained but hidden from the buyer
- Buyer must submit their own price for tracking resale data
- Admins see full price history; mods and others do not
### 🧪 Substrate + Fertilizer Tracking
- Track custom mixes by ingredient (e.g., “Fine Pumice”, “Large Bark”)
- Store cost per ingredient and auto-calculate total mix cost
- Recipes can be reused across plants
- Fertilizer schedules can be attached to logs and outcomes tracked
* **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
- When a plant is sold, sellers can add:
- Carrier, tracking number, est. delivery date
- Ownership updates post buyer confirmation
- Shipping logs are attached to the plant transfer log
* 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 folders (e.g., “For Sale”, “2025 Spring Batch”)
- Each folder gets its own QR code:
* 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}`
- Folders can be public, private, or unlisted
* 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.
---
## 🧍‍♂️ Users, Roles, and Groups
## 🔌 Plugin Ecosystem
### 👤 User Roles
- **User** – default
- **Moderator** – can manage flags, notes
- **Admin** – full backend, plugin, pricing, banning control
- Roles are extensible via admin UI
### 🛡 Moderator Panel
- View and resolve reports
- Add private notes to users or plants (e.g., warnings, suspicion)
- Ban users
- Banned users' plants become read-only
- Cannot add new plants
- Buyers can request transfer via email approval from banned seller
### 👥 Collaboration Groups
- Users can form groups to share:
- Logs
- Images
- Pricing (opt-in)
- Groups have role-based permissions (manager, editor, viewer)
- Useful for stores, teams, or shared collections
| 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 |
---
## 🏷️ Labeling System: QR + Barcode
## 📊 Data Models & Schema
### QR Code
- Generated on server after initial sync
- Unique to plant, never changes
- SVG and PNG available
Refer to `/migrations/` for full schema. Key tables include:
### Barcode Fallback
- CODE-128 format
- If data too long, split into stacked barcodes
- Same encoded info: plant ID, owner ID, visibility, timestamp
- Printable as label from dashboard
* `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`
---
## 🔐 Permissions Matrix
## 🛠 APIs & CLI
| Feature | Owner | Group Member | Moderator | Admin |
|--------------------------|-------|---------------|-----------|--------|
| View Logs | ✅ | ✅ (if shared) | ✅ | ✅ |
| Edit Logs | ✅ | 🔁* | 🚫 | ✅ |
| View Pricing | ✅ | ✅ (opt-in) | 🚫 | ✅ |
| Ban User / Flag Review | 🚫 | 🚫 | ✅ | ✅ |
| Approve Lineage | 🚫 | 🚫 | 🚫 | ✅ |
| Confirm Lineage | ✅ | 🚫 | 🚫 | ✅ |
* **REST**: `/api/v1/` CRUD, OpenAPI docs, JWT auth, rate limiting
* **GraphQL**: `/graphql` batched queries for plants + relations
* **CLI**:
🔁* if granted by group manager
* `flask db {init,migrate,upgrade}`
* `flask user create`
* `flask plugin {install,list,enable}`
* `flask preload-data`
---
## 🌍 Offline Sync (PWA)
- Full add/log/edit possible offline
- Sync queue uploads on connection
- QR/barcodes generated **after** server confirms sync
- Client-side validation before queue
## 🌐 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
---
## 🧠 Smart Tools
## 🔒 Security & Privacy
### ⭐️ User Reputation System
- Users rated after trades (accuracy, responsiveness, helpfulness)
- “Trusted Grower” tag auto-assigned above threshold
- Can be revoked via vote or admin action
### 🌿 Inter-Plant Comparison
- Timeline comparison for growth, size, or log outcomes
- Side-by-side charts and event overlays
* **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
---
## 🔧 Admin & Dev Tools
## 🛂 Permissions Matrix
### 📤 Seed Data Generator
- Seeds with common aroids, herbs, and test users
- Covers full range of roles, plant types, and edge cases
| 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 | ❌ | ❌ | ❌ | ✅ |
### 🗂 Plugin System
- CLI & plugin discovery system
- Admin can toggle plugins
- Plugin types: CLI, UI Panel, API extension, webhook, scheduler
### 🗃 Data Export / Disaster Recovery
- Export: SQL dump, file archive, JSON profile
- Restore: Admin-initiated rollback or full upload restore
\* if granted by group manager
---
## 🛣 API System
## ⚙ Admin & Dev Tools
### REST & GraphQL APIs
- REST: OpenAPI-documented endpoints
- GraphQL: Advanced multi-entity queries
- JWT-secured
- Follows role-based access rules
* **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 integration
- Language switcher in UI
- Community-managed translation interface (admin toggled)
## 🌍 Internationalization
* **Flask-Babel** for translations
* Language switcher in UI
* Community-managed translation portal (admin toggle)
---
## 📅 Future Enhancements
## 🛣 Roadmap & Future Enhancements
- 🧠 AI Journal Assistant (log suggestions, summarization)
- 📆 Calendar View for logs/reminders
- 🧰 Visual ERD Generator Tool
- 🛒 Live Auctions Plugin (for curated resale events)
* 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)
---