How iskracat/guillotina_stripe works
Project type and purpose
• This is a Python backend plugin package for the Guillotina REST framework that provides Stripe integration.
• Its core purpose is to handle subscription management and product purchases by delegating billing calls to Stripe and storing relevant state in Guillotina’s data store.
File structure
• Top-level artifacts:
• setup.py, README.rst, VERSION, CHANGELOG.rst
• guillotina_stripe/ (the main Python package)
• guillotina_stripe/tests/ (unit tests and fixtures)
• Within guillotina_stripe/:
• install.py — module that hooks the plugin into Guillotina at startup
• behavior.py & interfaces.py — define the behaviors (schemas) Guillotina objects will gain (e.g. “StripeSubscription” behavior)
• models.py — local persistence models that mirror Stripe objects (Customer, Subscription, Product, Card)
• product.py, subscription.py, cards.py, events.py, webhook.py — business logic for CRUD on Stripe resources, event subscribers, and HTTP webhook handlers
• util.py/utility.py — helper functions for mapping Guillotina objects ↔ Stripe API calls
• test_package.py & tests/* — validation of API interactions and payload handling
README for architecture hints
• “STRIPE backend for guillotina”
• “Designed to provide subscription management and product buying”
⇒ Confirms plugin-style architecture, no standalone UI, all logic lives inside Guillotina’s process.
a. Main components
1. Guillotina Core (Async HTTP server, request routing, behavior registry, event bus)
2. guillotina_stripe Plugin
3. External Stripe API (REST)
4. Data Store (e.g., PostgreSQL or MongoDB used by Guillotina)
5. HTTP/Webhook Endpoint (exposed by Guillotina for Stripe callbacks)
6. Event Bus inside Guillotina (for hooking into lifecycle events)
b. Relationships and interactions
• Incoming API call from client → Guillotina REST endpoint (e.g. POST /subscriptions)
• Guillotina routes to plugin’s subscription.py ⇒ calls Stripe Create Subscription API
• Stripe returns response → plugin updates local models (models.py) → commits to Data Store
• Stripe sends webhook on invoice.paid → Guillotina webhook route (webhook.py) → events.py subscribers process event → update models or fire further events
• Tests supply payloads (tests/payloads.py) to validate mapping logic in util.py
c. Architectural patterns & principles
• Plugin/modular architecture leveraging Guillotina behaviors & interfaces
• Event-driven design: webhooks & internal events trigger subscribers
• Asynchronous I/O via async/await for non-blocking Stripe HTTP calls
• Clean separation of concerns: API layer, business logic layer, persistence layer, integration layer
d. Key technologies & libraries
• Python 3.x, Asyncio
• Guillotina (application framework)
• Stripe REST API
• Zope-style Interfaces & Behaviors
• JSON payload schemas (in tests/payloads.py)
Capturing essential detail
• How an object with the StripeSubscription behavior triggers calls in models.py and util.py