Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
57 lines (46 loc) · 3.58 KB

ARCHITECTURE.md

File metadata and controls

57 lines (46 loc) · 3.58 KB

Paform Architecture

Paform extends the Vector Institute MVP template with a FastAPI backend and a Next.js frontend. It maintains strict decoupling between persistence, domain logic, and API boundaries.

Backend

  • Framework: FastAPI
  • Persistence: SQLAlchemy 2.x + Alembic
  • API Schemas: Pydantic v2 (DTOs) with ConfigDict(from_attributes=True)
  • Core services (pure, framework-agnostic):
    • Pricing Service: quote calculation using module dimensions and material surface area costs
    • CNC Service: naive panelization for MVP
    • Hygraph Service: webhook signature verification and idempotency

Data Model

  • Material: name, texture_url, cost_per_sq_ft, external_ids (JSONB), timestamps
  • Module: name, dimensions (width, height, depth), base_price, material_id, assembly_attributes, placement_constraints, connection_points, external_ids, timestamps
  • Order lifecycle tables (see below) capture the conversion funnel from quote acceptance through production handoff and payment capture.

Order lifecycle overview

  1. Quote acceptance – a confirmed quote spawns an orders record that freezes commercial terms (subtotal, tax, total, currency) and the buyer contact.
  2. Line-item normalization – order_line_items store each configured module with derived pricing metadata, decoupling repeatable catalog data from order-specific adjustments (discounts, finish overrides, shipping promises).
  3. Status tracking – every state transition (draft → pending_payment → design_review → production_ready → fulfilled/cancelled) is appended to order_status_events with actor metadata, making the audit trail queryable without denormalizing the orders table.
  4. Design collaboration – orders that require custom work spawn design_requests tied to the order (and optionally a specific line item). Each design request accumulates iterative assets in design_versions and design_assets (GLB, DXF, annotated PDFs) so the CAD pipeline can fetch the latest approved deliverable.
  5. Payment orchestration – payments represent the buyer’s financial obligations (deposit, balance, change order) and are linked to payment_transactions that mirror gateway intents/charges. Refunds and chargebacks are recorded in payment_adjustments, preserving immutable accounting while letting finance reconcile multiple providers.
  6. Downstream hooks – once an order is marked production_ready, event consumers enqueue manufacturing and logistics jobs using the normalized identifiers rather than scraping payload blobs.

Order lifecycle

Note

The source diagram lives in docs/assets/order-lifecycle-er.drawio and is exported to SVG automatically by build-docs.sh when Draw.io CLI tooling is available.

API Endpoints

  • GET /api/materials, CRUD
  • GET /api/modules, CRUD
  • POST /api/quote/generate
  • POST /api/v1/exports/cnc – generates CNC panels and returns S3 metadata (bucket, key, presigned url, content_type) for the cut list CSV and nesting SVG artifacts.
  • POST /api/sync/hygraph

Frontend

  • Next.js (App Router), Chakra UI, Zustand state
  • 3D: React Three Fiber + Drei
  • API client abstracts backend calls
  • Components:
    • Viewer3D: loads GLB with Draco and Suspense
    • ConfiguratorPanel, MaterialSelector

Assets

  • GLB files adhere to GLB_ASSET_STANDARD.md (node naming, material slots, metadata, LOD)

Testing

  • Backend: Pytest unit tests for services and route tests with TestClient
  • Frontend: Add Jest/RTL (future step)

Deployment

  • Docker Compose for dev/prod; SQLite dev, PostgreSQL prod (optional)