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