# shenleeosialai/oshen-comics architecture

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

- Interactive diagram: https://gitdiagram.com/shenleeosialai/oshen-comics
- Repository: https://github.com/shenleeosialai/oshen-comics

## Overview

##### Project Type & Purpose
- Full-stack, Django-based e-commerce web application.
- Purpose: allow users to browse comics & merchandise, manage carts, apply coupons, receive recommendations, and pay via M-Pesa or Stripe.
- Runs in Docker Compose with separate containers for web, workers, database, and Redis.

##### File Structure
- Top-level directories:
- account, cart, coupons, orders, payment, shop → Django apps implementing business domains.
- myshop/settings → multi-environment Django settings (base, local, prod).
- config/nginx & config/uwsgi → reverse-proxy and WSGI server configuration.
- data/cache → Redis dump for sessions/cache.
- static, templates → compiled front-end assets and site-wide templates.
- Docker-related: Dockerfile, docker-compose.yml, wait-for-it.sh.
- Celery integration: myshop/celery.py + orders.tasks, payment.tasks → background jobs.
- External API clients: payment/mpesa/client.py, Stripe SDK via Python.

##### README for Insights
- Confirm tech stack: Django, PostgreSQL, Redis (cache & broker), Celery, Nginx, uWSGI, Docker.

##### Main Components & Their Relationships
A. Client Layer (Browser / Mobile)
- Public user interface (templates rendered by Django).
- Admin interface (Django Admin under /admin).
B. Ingress Layer
- Docker-Compose “web” service includes Nginx reverse proxy (config/nginx/default.conf.template).
- uWSGI application server (config/uwsgi/uwsgi.ini) hosting Django.
C. Application Layer
- Django monolith with apps:
1. account (auth, profiles)
2. cart (Redis-backed session & cart logic)
3. coupons (coupon code logic)
4. shop (catalog, recommendations via shop.recommender)
5. orders (order placement, tracking, PDF receipts)
6. payment (MPesa & Stripe flows, webhooks)
- Celery worker(s) reading from Redis broker to handle email notifications, countdown deals, Mpesa polling.
D. Data Storage & Cache
- PostgreSQL container storing relational data (all Django models in each app).
- Redis container used as:
- Session store (cart, user sessions)
- Cache backend (Django cache for product lists, count-down deals)
- Celery broker (tasks queue).
E. External Services
- M-Pesa API endpoints for mobile payments.
- Stripe API for credit card payments.
F. Static & Media
- Django’s ‘static’ directory served via Nginx.
G. Docker & Deployment
- Docker Compose orchestrates services: web, worker, db (Postgres), cache (Redis).
- SSL termination at Nginx (ssl/myshop.crt, .key).

##### Data & Control Flows
- User → HTTPS → Nginx → uWSGI → Django view →
- Query/Post → PostgreSQL
- Session/Cache read-write → Redis
- Trigger background job → Celery (puts task in Redis)
- External API calls → M-Pesa / Stripe
- Render response → Nginx → User.
- Celery Worker → Redis (broker) → executes tasks (email, order fulfillment, Mpesa polling) → writes back to PostgreSQL or triggers outbound API calls.

##### Architectural Patterns & Design Principles
- Monolithic Django MVC (models, views, templates) with logical separation into apps.
- Containerized micro-services style orchestrated by Docker Compose.
- Asynchronous task pattern (Celery) for non-blocking background work.
- Cache-aside pattern with Redis for session & caching layers.
- Twelve-factor app compliance: environment-specific configs, stateless web processes, backing services as attached resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web Browser/Mobile"]:::client
        AdminUI["Django Admin (/admin)"]:::client
    end

    %% Ingress & Web Service
    subgraph "Web Service (Docker Container)" 
        direction TB
        NGINX["Nginx Reverse Proxy\n(HTTPS 443)"]:::web
        UWSGI["uWSGI Application Server"]:::web
        DjangoCore["Django Monolith"]:::app
        StaticFiles["Static Assets"]:::storage
        Templates["Templates"]:::storage
    end

    %% Django Apps
    subgraph "Django Apps" 
        direction TB
        Account["Account App"]:::app
        Cart["Cart App"]:::app
        Coupons["Coupons App"]:::app
        Shop["Shop App"]:::app
        Recommender["Shop Recommender"]:::app
        Orders["Orders App"]:::app
        PaymentApp["Payment App"]:::app
    end

    %% Worker Service
    subgraph "Worker Service (Celery)"
        direction TB
        CeleryWorker["Celery Worker"]:::worker
    end

    %% Data & Cache
    subgraph "Data Services"
        direction TB
        Postgres[(PostgreSQL\n5432)]:::db
        Redis[(Redis\n6379)]:::cache
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MPESA["M-Pesa API"]:::external
        Stripe["Stripe API"]:::external
    end

    %% Docker & Deployment
    subgraph "Deployment Assets"
        direction TB
        DockerCompose["docker-compose.yml"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        WaitForIt["wait-for-it.sh"]:::infra
        SSLCRT["ssl/myshop.crt"]:::infra
        SSLKEY["ssl/myshop.key"]:::infra
    end

    %% Flows
    Browser -->|HTTPS| NGINX
    AdminUI -->|HTTPS| NGINX
    NGINX -->|WSGI| UWSGI
    UWSGI -->|Invoke| DjangoCore
    DjangoCore -->|routes to| Account
    DjangoCore -->|routes to| Cart
    DjangoCore -->|routes to| Coupons
    DjangoCore -->|routes to| Shop
    DjangoCore -->|routes to| Orders
    DjangoCore -->|routes to| PaymentApp
    Shop -->|uses| Recommender

    DjangoCore -->|SQL Queries| Postgres
    DjangoCore -->|Session/Cache| Redis
    DjangoCore -->|Enqueue Task| CeleryWorker
    CeleryWorker -->|Broker| Redis
    CeleryWorker -->|Writes| Postgres
    CeleryWorker -->|MPesa Polling| MPESA
    CeleryWorker -->|Stripe Webhooks| Stripe

    PaymentApp -->|API Calls| MPESA
    PaymentApp -->|API Calls| Stripe

    DjangoCore -->|Serve| StaticFiles
    DjangoCore -->|Render| Templates

    %% Orchestration
    DockerCompose --> NGINX
    DockerCompose --> CeleryWorker
    DockerCompose --> Postgres
    DockerCompose --> Redis

    %% Click Events
    click Account "https://github.com/shenleeosialai/oshen-comics/tree/main/account/"
    click Cart "https://github.com/shenleeosialai/oshen-comics/tree/main/cart/"
    click Coupons "https://github.com/shenleeosialai/oshen-comics/tree/main/coupons/"
    click Shop "https://github.com/shenleeosialai/oshen-comics/tree/main/shop/"
    click Recommender "https://github.com/shenleeosialai/oshen-comics/blob/main/shop/recommender.py"
    click Orders "https://github.com/shenleeosialai/oshen-comics/tree/main/orders/"
    click PaymentApp "https://github.com/shenleeosialai/oshen-comics/tree/main/payment/"
    click MPESA "https://github.com/shenleeosialai/oshen-comics/blob/main/payment/mpesa/client.py"
    click CeleryWorker "https://github.com/shenleeosialai/oshen-comics/blob/main/myshop/celery.py"
    click Orders "https://github.com/shenleeosialai/oshen-comics/blob/main/orders/tasks.py"
    click PaymentApp "https://github.com/shenleeosialai/oshen-comics/blob/main/payment/tasks.py"
    click Settings "https://github.com/shenleeosialai/oshen-comics/tree/main/myshop/settings/"
    click WSGI "https://github.com/shenleeosialai/oshen-comics/blob/main/myshop/wsgi.py"
    click ASGI "https://github.com/shenleeosialai/oshen-comics/blob/main/myshop/asgi.py"
    click URLs "https://github.com/shenleeosialai/oshen-comics/blob/main/myshop/urls.py"
    click NGINX "https://github.com/shenleeosialai/oshen-comics/blob/main/config/nginx/default.conf.template"
    click UWSGI "https://github.com/shenleeosialai/oshen-comics/blob/main/config/uwsgi/uwsgi.ini"
    click DockerCompose "https://github.com/shenleeosialai/oshen-comics/blob/main/docker-compose.yml"
    click DockerfileNode "https://github.com/shenleeosialai/oshen-comics/tree/main/Dockerfile"
    click WaitForIt "https://github.com/shenleeosialai/oshen-comics/blob/main/wait-for-it.sh"
    click SSLCRT "https://github.com/shenleeosialai/oshen-comics/blob/main/ssl/myshop.crt"
    click SSLKEY "https://github.com/shenleeosialai/oshen-comics/blob/main/ssl/myshop.key"
    click StaticFiles "https://github.com/shenleeosialai/oshen-comics/tree/main/static/"
    click Templates "https://github.com/shenleeosialai/oshen-comics/tree/main/templates/"
    click Redis "https://github.com/shenleeosialai/oshen-comics/blob/main/data/cache/dump.rdb"

    %% Styles
    classDef client fill:#C6E5FF,stroke:#2B7FFF,color:#000
    classDef web fill:#FFE5C6,stroke:#FF7F2B,color:#000
    classDef app fill:#E5FFC6,stroke:#7FFF2B,color:#000
    classDef worker fill:#FFD1DC,stroke:#FF1F4B,color:#000
    classDef db fill:#FFCCCC,stroke:#FF0000,color:#000
    classDef cache fill:#FFE5CC,stroke:#FFAA00,color:#000
    classDef external fill:#F0F0F0,stroke:#888888,color:#000,stroke-dasharray: 5 5
    classDef storage fill:#F5E6FF,stroke:#8B2BE2,color:#000
    classDef infra fill:#D9D9D9,stroke:#666666,color:#000,stroke-dasharray: 2 2
```
