# iskracat/guillotina_stripe architecture

> Architecture diagram of the GitHub repository iskracat/guillotina_stripe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iskracat/guillotina_stripe
- Repository: https://github.com/iskracat/guillotina_stripe

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External client
    Client["Client"]:::external

    %% Guillotina Core
    subgraph "Guillotina Core" 
        direction TB
        Router["Request Router"]:::internal
        BehRegCore["Behavior Registry"]:::internal
        EventBusCore["Event Bus"]:::internal
        subgraph "guillotina_stripe Plugin" 
            direction TB
            Install["Behavior Registration Module\n(install.py)"]:::internal
            Behavior["Behavior Schemas\n(behavior.py)"]:::internal
            Interfaces["Behavior Interfaces\n(interfaces.py)"]:::internal
            SubscriptionSvc["Subscription Service\n(subscription.py)"]:::internal
            ProductSvc["Product Service\n(product.py)"]:::internal
            CardsSvc["Cards Service\n(cards.py)"]:::internal
            WebhookHandler["Webhook Handler\n(webhook.py)"]:::internal
            EventSubs["Event Subscribers\n(events.py)"]:::internal
            Models["Persistence Models\n(models.py)"]:::internal
            Util["Utility Helpers\n(util.py/utility.py)"]:::internal
        end
    end

    %% External Stripe API
    StripeAPI["Stripe REST API"]:::external

    %% Data Store
    DataStore["Data Store"]:::datastore

    %% Tests and config
    Setup["Package Configuration\n(setup.py)"]:::internal
    Docs["Documentation & Metadata\n(README.rst, VERSION,\nCHANGELOG.rst)"]:::internal
    subgraph "Plugin Test Suite"
        Tests["Tests & Fixtures\n(test_package.py,\n/tests/)"]:::test
    end

    %% Connections
    Client -->|"HTTP Request"| Router
    Router -->|"routes to"| SubscriptionSvc
    SubscriptionSvc -->|"calls Stripe"| StripeAPI
    StripeAPI -->|"response"| SubscriptionSvc
    SubscriptionSvc -->|"update"| Models
    Models -->|"persist"| DataStore

    StripeAPI -.->|"webhook callback"| WebhookHandler
    WebhookHandler -->|"triggers"| EventSubs
    EventSubs -->|"updates"| Models
    Models -->|"persist"| DataStore

    Install --> BehRegCore
    Behavior --> BehRegCore
    Interfaces --> BehRegCore
    Router --> Install

    Util --> SubscriptionSvc
    Util --> ProductSvc
    Util --> CardsSvc
    Util --> WebhookHandler
    Util --> EventSubs

    ProductSvc -->|"calls Stripe"| StripeAPI
    CardsSvc -->|"calls Stripe"| StripeAPI

    %% Tests
    Tests --> Util
    Tests --> SubscriptionSvc
    Tests --> WebhookHandler

    %% Config and Docs
    Setup --> Install
    Docs --> Install

    %% Click Events
    click Install "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/install.py"
    click Behavior "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/behavior.py"
    click Interfaces "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/interfaces.py"
    click Models "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/models.py"
    click SubscriptionSvc "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/subscription.py"
    click ProductSvc "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/product.py"
    click CardsSvc "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/cards.py"
    click WebhookHandler "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/webhook.py"
    click EventSubs "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/events.py"
    click Util "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/util.py"
    click Util "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/utility.py"
    click Tests "https://github.com/iskracat/guillotina_stripe/blob/master/guillotina_stripe/test_package.py"
    click Tests "https://github.com/iskracat/guillotina_stripe/tree/master/guillotina_stripe/tests/"
    click Setup "https://github.com/iskracat/guillotina_stripe/blob/master/setup.py"
    click Docs "https://github.com/iskracat/guillotina_stripe/blob/master/README.rst"
    click Docs "https://github.com/iskracat/guillotina_stripe/tree/master/VERSION"
    click Docs "https://github.com/iskracat/guillotina_stripe/blob/master/CHANGELOG.rst"

    %% Styles
    classDef internal fill:#D5E8D4,stroke:#4CAF50,color:#333;
    classDef external fill:#E1F5FE,stroke:#0277BD,color:#333;
    classDef datastore fill:#FFE0B2,stroke:#FB8C00,color:#333;
    classDef test fill:#F3E5F5,stroke:#8E24AA,color:#333;
```
