natureinpots_community/README.md

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

2. Architecture & Tech Stack

3. Quickstart & Installation

4. Project Structure

5. Core Features

   1. Plant Profiles
   2. Grow Logs
   3. Verified Lineage Tracking
   4. Pricing Logic
   5. Substrate & Fertilizer Tracking
   6. Shipping Tracker
   7. Plant Folders
   8. Media Gallery & Voting
   9. QR & Barcode Labeling
   10. Offline Sync (PWA)
   11. Smart Tools

6. Plugin Ecosystem

7. Data Models & Schema

8. APIs & CLI

9. User Interface & PWA

10. Security & Privacy

11. Permissions Matrix

12. Admin & Dev Tools

13. Internationalization

14. Roadmap & Future Enhancements

15. Contributing

16. 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

   git clone https://github.com/yourorg/nip-community.git
   cd nip-community
   

2. Virtualenv & Dependencies

   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

   flask db init  
   flask db migrate  
   flask db upgrade
   

5. Run

   flask run --reload
   

   Access 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.