juntagrico

juntagrico is a Python‑based web platform that orchestrates the day‑to‑day operations of community gardens and vegetable cooperatives. At its core it offers subscription, share, delivery, and member management, all exposed through a REST‑like API and an admin interface built on Django’s robust MVC framework. The application is designed for self‑hosting, providing a full stack that can be deployed on any Linux server or containerized environment.

Technical Stack

• Language & Framework: Python 3.8+ with Django 4.x, leveraging the ORM for relational data and signals for business logic.
• Database: PostgreSQL is the recommended backend, with support for SQLite during development. The schema is generated via Django migrations and includes tables for Subscription, Share, Delivery, Member, and related lookup entities.
• Templating & Frontend: Server‑side rendering with Django templates, enhanced by Alpine.js for lightweight interactivity. The UI follows a responsive design that adapts to mobile devices without requiring a separate SPA.
• Testing & CI: Continuous integration runs on GitHub Actions, covering unit tests, linting (flake8), and test coverage checks. The repository includes a tox environment for running tests across multiple Python versions.

Core Capabilities & APIs

• Subscription Management: CRUD operations for base and extra subscriptions, with support for recurring billing periods. The API exposes endpoints like /api/subscriptions/ that return JSON payloads containing member links, pricing, and status flags.
• Share & Delivery Logic: A sophisticated algorithm assigns shares to members based on subscription tiers and manages delivery schedules. Developers can hook into the delivery_created signal to integrate with external logistics or notification services.
• Member & Role Management: Custom Django User model extensions allow role‑based permissions (admin, manager, member). The admin panel provides bulk import/export via CSV, which can be scripted for automated onboarding.
• Webhooks & Extensibility: The platform supports outbound webhooks that notify external services on key events (e.g., new subscription, payment failure). Additionally, developers can write Django apps that plug into the existing signal framework to add new features or modify workflows.

Deployment & Infrastructure

juntagrico is engineered for self‑hosting. A typical deployment stack includes:

1. Web Server: Gunicorn or Uvicorn behind Nginx, with HTTPS termination via Let’s Encrypt.
2. Database: PostgreSQL running in a Docker container or on the host; schema migrations are handled by Django’s migrate command.
3. Background Tasks: Celery with Redis as the broker for scheduled deliveries and email notifications.
4. Containerization: Official Docker images are available on Docker Hub, enabling quick spin‑up in Kubernetes or Docker Compose environments. The docker-compose.yml file demonstrates a minimal production setup.

Scalability is achieved by horizontally scaling the Django workers and using a shared Redis instance. The application’s stateless nature (apart from session storage) makes it straightforward to add replicas behind a load balancer.

Integration & Extensibility

• Plugin System: While there is no formal plugin API, the open‑source nature of Django allows developers to fork the repository or create separate apps that import models and signals. Custom middleware can be added for authentication (e.g., OAuth2) or audit logging.
• APIs & Webhooks: The REST endpoints are documented in OpenAPI format, enabling automated client generation. Webhook payloads include HMAC signatures for secure verification.
• Custom Fields: The data model can be extended with JSONField columns, allowing ad‑hoc attributes without schema migrations for small tweaks.

Developer Experience

• Documentation: Comprehensive docs are hosted on ReadTheDocs, covering installation, configuration, and API usage. The README includes CI badges and a live demo link for quick validation.
• Community & Support: The project is actively maintained on GitHub, with a healthy issue tracker and code‑review process. Licensing under the MIT license encourages commercial use without restrictions.
• Configuration: Settings are split into settings.py and environment variables, enabling developers to override defaults for production. The DJANGO_SETTINGS_MODULE can point to a custom module for staging or testing environments.

Use Cases

• Community Garden Operators: Automate member enrollment, subscription billing cycles, and delivery routing.
• Cooperative Food Producers: Track share allocations per farmer, manage per‑subscription pricing, and integrate with POS systems via webhooks.
• Event Organizers: Use the member management API to sell tickets for seasonal harvest events, with real‑time updates on availability.

Advantages

• Performance & Flexibility: Django’s mature ORM and caching layers provide fast query handling, while the Python ecosystem allows rapid feature development.
• Licensing: MIT license removes barriers for commercial deployment, unlike proprietary CSA solutions that lock in pricing.
• Extensibility: The signal‑driven architecture lets developers inject custom logic without modifying core code, preserving upgrade paths.
• Community & Documentation: A well‑maintained open‑source project with live demos and CI integration gives developers confidence in stability and support.

In summary, juntagrico delivers a feature‑rich, self‑hosted platform that balances ease of use for garden operators with the flexibility developers need to tailor workflows, integrate external services, and scale alongside growing communities.