Paform Platform

Paform delivers a configurable cabinetry experience end-to-end: shoppers explore parametric models in 3D, pricing is generated in real time, and accepted designs flow through Shopify and Odoo for fulfillment. This repository contains the full stack—Next.js frontend, FastAPI backend, background workers, and operational automation—wired together for local development, CI, and production.

Highlights

• Parametric product experience – React Three Fiber viewer integrates with the PartCAD adapter to stream GLB renders and bills of materials.
• Quote-to-order pipeline – FastAPI services normalize pricing, persist quotes, and push approved orders into Shopify and Odoo.
• Production-ready ops – Docker Compose stacks for dev/CI/prod, observability via OpenTelemetry + Prometheus, and hardening (rate limiting, health checks, log rotation).

Architecture Overview

Paform follows the split described in docs/ARCHITECTURE.md. At a glance:

• Frontend (frontend/)
  • Next.js (App Router) with TypeScript, Chakra UI, Zustand, and React Three Fiber.
  • Polling shell for PartCAD renders with guarded timeouts (frontend/components/PartcadViewerShell.tsx).
  • GraphQL codegen for Hygraph content and Playwright E2E coverage.
• Backend (backend/)
  • FastAPI 0.112+ instrumented with Prometheus and OpenTelemetry.
  • Domain services for pricing, CNC exports, Shopify order sync, and PartCAD streaming.
  • PostgreSQL via SQLAlchemy 2.x + Alembic migrations; Redis-backed rate limiting.
• Supporting services
  • PartCAD renderer, Redis, PostgreSQL, and Odoo (for ERP handoff).
  • Caddy edge proxy (TLS, API routing, rate limiting) defined in ops/prod/Caddyfile.
  • CI Compose stack in docker/ci.compose.yml and hardened prod stack under ops/prod/.

Local Development

Prerequisites

• Docker & Docker Compose (20.10+)
• Python 3.12 with uv for backend deps
• Node.js 20 (Homebrew path handled automatically in scripts/dev.sh)
• Optional: Draw.io CLI for regenerating architecture diagrams

Quick Start (Docker)

cp .env.example .env.development
docker compose --env-file .env.development -f docker-compose.dev.yml up --build

Services expose:

• Frontend (Next.js dev server): http://localhost:${FRONTEND_PORT:-3000}
• Backend API + docs: http://localhost:${BACKEND_PORT:-8000}
• Odoo (dev profile): http://localhost:8069
• PostgreSQL: localhost:5432

To preview 3D assets and pricing workflow end-to-end, run the scripted demo:

scripts/demo.sh

Running Without Docker

# Backend (FastAPI / uvicorn)
cd backend
uv venv
source .venv/bin/activate
uv pip sync pyproject.toml
uvicorn backend.main:app --reload

# Frontend (Next.js)
cd frontend
npm install
npm run dev

scripts/dev.sh launches either service (scripts/dev.sh be / scripts/dev.sh fe) and handles port cleanup, log redirection, and required environment checks.

Environment Configuration

Key files to keep in sync across environments:

• .env.example – base template for local development
• .env.development – docker-compose.dev overrides
• secrets/prod.env – source of truth for deploy secrets (rendered into ops/prod/*.env)
• backend.env.template & ops/prod/backend.env.template – variables consumed by prod Compose stacks

Testing & Quality

Layer	Command	Notes
Backend	cd backend && uv run pytest	Includes API/service unit tests and integration
Typing	cd backend && uv run mypy	Strict mode; middleware redaction path covered
Frontend	cd frontend && npm run test	Jest/RTL suite
E2E	cd frontend && npm run test:e2e	Playwright against running dev services
Linting	pre-commit run --all-files	Ruff, ESLint, formatting

CI (.github/workflows/*.yml) runs backend + frontend gates plus container smoke tests on every PR.

Deployment

Production Compose Stack

ops/prod/docker-compose.yml orchestrates:

• caddy – TLS termination, API routing (/api/* to backend) and static caching
• frontend – Next.js build output served by Node (non-root user, health checks)
• backend – FastAPI app packaged via ops/prod/Dockerfile.backend
• redis, db (PostgreSQL 16.4), odoo (18.0) with health-checked dependencies

Required secrets are injected via ops/prod/backend.env and ops/prod/frontend.env (rendered from secrets/prod.env). Data directories mount under ops/data/*.

Observability

• Prometheus metrics exposed at /metrics (scraped by Instrumentator)
• OpenTelemetry traces exported via OTLP; configure endpoint in env vars
• Structured access logging with email redaction (backend/middleware/scrub.py)
• docker-compose.observability.yml spins up Prometheus, Grafana, Loki, Tempo, Pushgateway, and the OTEL Collector for local inspection
• Log rotation rules live in ops/logrotate.conf

Documentation

• Static site generated with MkDocs Material; browse at https://shayancoin.github.io/paform/
• Authoritative docs live under docs/ (architecture, API spec, release checklist, runbooks)
• Update diagrams via build-docs.sh (requires drawio CLI)

Project Resources

• ACCEPTANCE.md – release gates before landing on main
• docs/API_SPEC.md – backing contract for frontend/client integrations
• scripts/ – automation for demos, waits, smoke tests, and orchestration
• ops/ – infrastructure-as-code (Caddy, logrotate, prod Compose)

License

Paform is distributed under the Apache-2.0 License. See LICENSE.md for details.