# leanstix/micro_commerce architecture

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

- Interactive diagram: https://gitdiagram.com/leanstix/micro_commerce
- Repository: https://github.com/leanstix/micro_commerce

## Overview

##### Project Type & Purpose
- This is a full-stack “micro-commerce” application composed of:
- A React Native client built with Expo (directory: client/)
- A Django + Django REST Framework backend (directory: server/)
- A local SQLite database (server/db.sqlite3) and local media file storage (server/media/)
- Built-in Django Admin UI for product/order management

##### File Structure & Architectural Patterns
- Top-level directories:
- client/: Expo/React Native app
- server/: Django project (“microcommerce”) + shop app
- client/app/(tabs)/…, client/components/, client/lib/ ⇒ UI screens, shared components, API/session/theme helpers ⇒ Presentation layer
- server/microcommerce/: project settings, URL routing, ASGI/WSGI entry points ⇒ Configuration & core app
- server/shop/: models, serializers, views, auth_views, services (checkout logic), management/commands (seed_shop) ⇒ Business logic layer
- server/docker-compose.yml & Dockerfile ⇒ containerization/deployment
- Patterns:
- REST API layer (DRF)
- JWT authentication + guest cart via X-Session-Key header
- ORM layer → SQLite dev (PostgreSQL in prod)
- File-based media serving via MEDIA_URL/MEDIA_ROOT
- Stateless client, stateful session-key management, merge logic

##### Main Components
a. Client (Expo React Native)
- Screens: product grid, cart, orders, account, checkout, login/signup/verify
- Helpers: API client (client/lib/api.js), AsyncStorage for tokens & session key, SmartImage (native & web)
b. API Gateway (Django REST Framework)
- Auth endpoints (/api/auth/signup, verify, login, me)
- Products endpoints (/api/products, /api/products/:id)
- Cart endpoints (/api/cart, /api/cart/items)
- Orders endpoints (/api/orders/checkout, /api/orders/me, /api/orders/:id)
- Middleware: CORS, SimpleJWT, session-key merger on every authenticated request
c. Persistence Layer
- Database (SQLite dev / PostgreSQL prod) – models: Product, Cart, CartItem, Order, OrderItem
- Media file storage on disk under server/media/products
d. Admin UI
- Built-in Django Admin (http://…/admin/) for managing Products, Orders, Users
e. External Services (optional)
- Email backend (console in dev, SMTP in prod) for verification links
- Expo asset caching (expo-image)

##### Relationships & Data Flows
- Client → API:
- All requests include X-Session-Key header; after login, also Authorization: Bearer <JWT>
- Data flows: fetch products → render list; add to cart → POST /api/cart/items; checkout → POST /api/orders/checkout; login/signup flows
- API → Database: ORM queries for CRUD on products, cart items, orders
- API → Media Store: serve product images via MEDIA_URL endpoints
- API → Email Service: send verification link on signup (console backend)
- Admin UI ↔ API: Django Admin views talk directly to ORM & database

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (client) / API (Django REST) / Persistence (DB + media)
- Stateless REST with token-based auth + idempotent guest→user cart merging
- Modular code organization: shop app for business logic & DRF serializers/views, management commands for data seeding
- Containerizable via Docker/Docker-Compose for dev & prod parity

##### Technologies & Frameworks
- Frontend: Expo Router, React Native, expo-image, AsyncStorage, useFocusEffect for tab re-fetch
- Backend: Django, Django REST Framework, djangorestframework-simplejwt, django-cors-headers, Pillow
- DB: SQLite (dev), PostgreSQL (prod)
- Deployment: Docker, docker-compose

##### Critical Details to Capture
- Guest cart via X-Session-Key header and merge logic on login/each request
- JWT issuance and usage for authenticated flows
- Local media serving via `/media/products/...` and SmartImage converting relative URLs
- Admin UI bypassing the API layer (direct ORM access) if desired, or show it as part of the API layer
- Docker/Docker-Compose boundary (optional)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UIRoot["Expo React Native App"]:::frontend
        subgraph "Screens" 
            direction TB
            Home["Product Grid (Home)"]:::frontend
            CartScreen["Cart"]:::frontend
            OrdersList["Orders List"]:::frontend
            Account["Account"]:::frontend
            Checkout["Checkout"]:::frontend
            Login["Login"]:::frontend
            Signup["Signup"]:::frontend
            Verify["Verify Email"]:::frontend
            ProductDetail["Product Detail"]:::frontend
            OrderDetail["Order Detail"]:::frontend
            AdminView["Admin View in App"]:::frontend
        end
        subgraph "Components" 
            direction TB
            ProductCard["ProductCard"]:::frontend
            Skeleton["Skeleton"]:::frontend
            SmartImage["SmartImage"]:::frontend
        end
        subgraph "Helpers (Lib)" 
            direction TB
            APIClient["api.js"]:::frontend
            SessionStore["session.js"]:::frontend
            Theme["theme.js"]:::frontend
            FocusHook["focusRefresh.js"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Middleware["Middleware: CORS, JWT, Session Merge"]:::api
        subgraph "Auth Endpoints" 
            direction TB
            Auth["/api/auth (signup, login, verify, me)"]:::api
        end
        subgraph "Products Endpoints"
            direction TB
            Products["/api/products"]:::api
        end
        subgraph "Cart Endpoints"
            direction TB
            CartAPI["/api/cart"]:::api
        end
        subgraph "Orders Endpoints"
            direction TB
            OrdersAPI["/api/orders"]:::api
        end
        AdminUI["Django Admin UI"]:::api
    end

    %% Persistence & Services Layer
    subgraph "Persistence & Services"
        direction TB
        Database["Database (SQLite/PostgreSQL)"]:::persistence
        MediaStore["Media Storage (server/media/products)"]:::persistence
        EmailService["Email Service"]:::service
    end

    %% Connections: Frontend -> API
    UIRoot -->|uses| Home
    UIRoot -->|uses| CartScreen
    UIRoot -->|uses| OrdersList
    UIRoot -->|uses| Account
    UIRoot -->|uses| Checkout
    UIRoot -->|uses| Login
    UIRoot -->|uses| Signup
    UIRoot -->|uses| Verify
    UIRoot -->|uses| ProductDetail
    UIRoot -->|uses| OrderDetail
    UIRoot -->|uses| AdminView

    Home -->|HTTP GET, X-Session-Key| Products
    ProductDetail -->|HTTP GET| Products
    CartScreen -->|HTTP GET/POST| CartAPI
    Checkout -->|HTTP POST| OrdersAPI
    OrdersList -->|HTTP GET| OrdersAPI
    OrderDetail -->|HTTP GET| OrdersAPI
    Login -->|HTTP POST| Auth
    Signup -->|HTTP POST| Auth
    Verify -->|HTTP POST| Auth
    AdminView -->|HTTP via API or bypass| AdminUI

    %% API internal
    Middleware --> Auth
    Middleware --> Products
    Middleware --> CartAPI
    Middleware --> OrdersAPI

    %% API -> Persistence & Services
    Auth -->|DB CRUD| Database
    Products -->|ORM Queries| Database
    CartAPI -->|ORM Queries| Database
    OrdersAPI -->|ORM Queries| Database
    Products -->|serve images| MediaStore
    Auth -->|send email| EmailService
    AdminUI -->|ORM Access| Database

    %% Click Events: Frontend
    click UIRoot "https://github.com/leanstix/micro_commerce/tree/main/client/"
    click Home "https://github.com/leanstix/micro_commerce/blob/main/client/app/(tabs)/index.js"
    click CartScreen "https://github.com/leanstix/micro_commerce/blob/main/client/app/(tabs)/cart.js"
    click OrdersList "https://github.com/leanstix/micro_commerce/blob/main/client/app/(tabs)/orders.js"
    click Account "https://github.com/leanstix/micro_commerce/blob/main/client/app/(tabs)/account.js"
    click Checkout "https://github.com/leanstix/micro_commerce/blob/main/client/app/checkout.js"
    click Login "https://github.com/leanstix/micro_commerce/blob/main/client/app/login.js"
    click Signup "https://github.com/leanstix/micro_commerce/blob/main/client/app/signup.js"
    click Verify "https://github.com/leanstix/micro_commerce/blob/main/client/app/verify.js"
    click ProductDetail "https://github.com/leanstix/micro_commerce/blob/main/client/app/product/[id].js"
    click OrderDetail "https://github.com/leanstix/micro_commerce/blob/main/client/app/orders/[id].js"
    click AdminView "https://github.com/leanstix/micro_commerce/blob/main/client/app/admin/products.js"
    click ProductCard "https://github.com/leanstix/micro_commerce/blob/main/client/components/ProductCard.js"
    click Skeleton "https://github.com/leanstix/micro_commerce/blob/main/client/components/Skeleton.js"
    click SmartImage "https://github.com/leanstix/micro_commerce/blob/main/client/components/SmartImage.js"
    click APIClient "https://github.com/leanstix/micro_commerce/blob/main/client/lib/api.js"
    click SessionStore "https://github.com/leanstix/micro_commerce/blob/main/client/lib/session.js"
    click Theme "https://github.com/leanstix/micro_commerce/blob/main/client/lib/theme.js"
    click FocusHook "https://github.com/leanstix/micro_commerce/blob/main/client/lib/focusRefresh.js"

    %% Click Events: API
    click Middleware "https://github.com/leanstix/micro_commerce/blob/main/server/microcommerce/settings.py"
    click Auth "https://github.com/leanstix/micro_commerce/blob/main/server/shop/auth_views.py"
    click Products "https://github.com/leanstix/micro_commerce/blob/main/server/shop/views.py"
    click CartAPI "https://github.com/leanstix/micro_commerce/blob/main/server/shop/views.py"
    click OrdersAPI "https://github.com/leanstix/micro_commerce/blob/main/server/shop/views.py"
    click AdminUI "https://github.com/leanstix/micro_commerce/blob/main/server/shop/admin.py"
    click Database "https://github.com/leanstix/micro_commerce/blob/main/server/shop/models.py"
    click MediaStore "https://github.com/leanstix/micro_commerce/tree/main/server/media/products/"
    click EmailService "https://github.com/leanstix/micro_commerce/blob/main/server/microcommerce/settings.py"

    %% Class Definitions
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#D6FFD6,stroke:#333,stroke-width:1px
    classDef persistence fill:#FFF8B8,stroke:#333,stroke-width:1px
    classDef service fill:#EEEEEE,stroke:#333,stroke-width:1px
```
