### Setup Python Virtual Environment and Run Backend (Bash)

Source: https://github.com/shayancoin/paform/blob/main/docs/getting-started.md

Sets up a Python virtual environment using 'uv', installs backend development dependencies, and starts the Uvicorn server for the backend API with hot reloading. Requires Python, 'uv', and 'uvicorn'.

```bash
cd backend
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
uvicorn api.main:app --reload
```

--------------------------------

### Install Frontend Dependencies and Start Dev Server (Bash)

Source: https://github.com/shayancoin/paform/blob/main/docs/getting-started.md

Installs Node.js dependencies for the frontend and starts the development server with hot reloading. Requires Node.js and npm.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Clone and Navigate Repository (Bash)

Source: https://github.com/shayancoin/paform/blob/main/docs/getting-started.md

Clones the project repository from GitHub and navigates into the newly created directory. Assumes you have Git installed.

```bash
git clone https://github.com/yourusername/your-new-repo.git
cd your-new-repo
```

--------------------------------

### Copy Environment File (Bash)

Source: https://github.com/shayancoin/paform/blob/main/docs/getting-started.md

Copies the example environment file to a new file for development configuration. This is a common step for managing project-specific settings.

```bash
cp .env.example .env.development
```

--------------------------------

### Install and Setup uv for Python Package Management

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

This snippet shows how to install uv, a fast Python package manager, and use it to create a virtual environment and install project dependencies. It assumes you are in the backend directory of the project.

```bash
# Install uv if you don't have it
pip install uv

# Navigate to the backend directory
cd backend

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies including development packages
uv pip install -e ".[dev]"
```

--------------------------------

### Start Development Services with Docker Compose (Bash)

Source: https://github.com/shayancoin/paform/blob/main/docs/getting-started.md

Launches frontend and backend services in development mode using Docker Compose. It specifies the environment file and the Docker Compose configuration file.

```bash
docker compose --env-file .env.development -f docker-compose.dev.yml up
```

--------------------------------

### Install Dependencies and Start Local Development (Bash)

Source: https://github.com/shayancoin/paform/blob/main/frontend/README.md

Installs project dependencies and starts the Next.js development server for local testing. Ensure you are in the project's root directory before running these commands.

```bash
npm install
npm run dev
```

--------------------------------

### Link and Push Supabase Schema

Source: https://github.com/shayancoin/paform/blob/main/docs/quick-start/supabase.md

This command links the local Supabase CLI to a specific project and pushes the schema definitions, including authentication helpers and RLS policies, to the Supabase project. Ensure you have the Supabase CLI installed and authenticated.

```bash
supabase link --project-ref <project-ref>
supabase db push
```

--------------------------------

### Build Script for Production Deployment

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

Example of using a build script to deploy the production environment. It first sets the environment to 'production', runs the build script, and then starts the Docker Compose services for production.

```bash
ENVIRONMENT=production ./build.sh
docker compose --env-file .env.production -f docker-compose.yml up -d
```

--------------------------------

### Start Development with Docker/Helper Script (Bash)

Source: https://github.com/shayancoin/paform/blob/main/frontend/README.md

Initiates the frontend development environment using a helper script, assuming the script is located at the repository root. This method streamlines the setup for local development.

```bash
# From the repository root
scripts/dev.sh fe
```

--------------------------------

### Write a Pytest Test Case for a Service Method

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

An example of a pytest test class for a service. It demonstrates setting up the service instance before each test and asserting the expected output of a service method.

```python
"""Tests for new service."""

from services.new_service import NewService

class TestNewService:
    """Tests for NewService."""

    def setup_method(self) -> None:
        """Set up test fixtures."""
        self.service = NewService()

    def test_some_method(self) -> None:
        """Test some_method."""
        result = self.service.some_method()
        assert result == "Result"
```

--------------------------------

### Run FastAPI Backend Server with Uvicorn

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

This command starts the FastAPI backend server using uvicorn, enabling live reloading for development. Ensure your virtual environment is activated before running this command.

```bash
# With the virtual environment activated
uvicorn api.main:app --reload
```

--------------------------------

### Install and Run FastAPI Backend Locally

Source: https://github.com/shayancoin/paform/blob/main/backend/README.md

Installs the backend in development mode using pip and then runs the development server using uvicorn. This is the primary method for local development and testing.

```bash
pip install -e .

uvicorn api.main:app --reload
```

--------------------------------

### Build and Run Production Environment with Docker Compose

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

Shell commands to build and run the production Docker environment. This involves setting a build ID, building the containers using a production compose file and environment, and then starting them in detached mode.

```bash
# Set the BUILD_ID environment variable
export BUILD_ID=$(date +%Y%m%d%H%M%S)

# Build the containers
docker compose --env-file .env.production -f docker-compose.yml build

# Run the containers
docker compose --env-file .env.production -f docker-compose.yml up -d
```

--------------------------------

### Copy Terraform Variables Example

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

Copies the example Terraform variables file to a new file for environment-specific configuration. This is a common first step in setting up Terraform for a project.

```bash
cp ops/terraform/terraform.tfvars.example ops/terraform/terraform.tfvars
```

--------------------------------

### Start Local Development with Docker Compose

Source: https://github.com/shayancoin/paform/blob/main/README.md

This snippet demonstrates how to initiate the Paform local development environment using Docker Compose. It requires a `.env.development` file to be present, which is a copy of `.env.example`. This command builds and starts all necessary services defined in `docker-compose.dev.yml`.

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

--------------------------------

### Add a New Service to Docker Compose

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

YAML configuration example for adding a new service to a Docker Compose file. It includes essential directives like `build` (specifying context and Dockerfile), `environment` variables, exposed `ports`, and network configuration.

```yaml
new-service:
  build:
    context: ./new-service
    dockerfile: Dockerfile
  environment:
    - VARIABLE=value
  ports:
    - "1234:1234"
  networks:
    - app-network
```

--------------------------------

### Frontend Volume Mount in Docker Compose (Development)

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

YAML configuration snippet showing how to mount the frontend source code directory as a volume in a Docker Compose setup. This enables hot-reloading by linking the host's `./frontend` directory to the container's `/app` directory and excludes `node_modules` from the host.

```yaml
volumes:
  - ./frontend:/app
  - /app/node_modules
```

--------------------------------

### Run Playwright End-to-End Tests

Source: https://github.com/shayancoin/paform/blob/main/docs/quick-start/supabase.md

This command executes Playwright end-to-end tests to validate the Supabase policies and dealer portal functionalities. It ensures that the Supabase RPC helpers and row-level security rules are configured correctly.

```bash
npx playwright test tests/playwright/dealer-portal.spec.ts
```

--------------------------------

### Create a New Service Class in Python

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

Demonstrates how to create a new service class for business logic. This includes initializing the class and defining a method that performs an operation and returns a result.

```python
"""New service module."""

class NewService:
    """New service class."""

    def __init__(self) -> None:
        """Initialize the new service."""
        pass

    def some_method(self) -> str:
        """Do something.

        Returns
        -------
        str
            Result of the operation.
        """
        return "Result"
```

--------------------------------

### Zustand State Management Example

Source: https://github.com/shayancoin/paform/blob/main/docs/frontend-development.md

An example TypeScript snippet demonstrating how to define and use a Zustand store for managing application state, specifically for tracking a loading status. It utilizes the `create` function from Zustand to define the store.

```typescript
import { create } from 'zustand';

interface AppState {
  isLoading: boolean;
  setIsLoading: (isLoading: boolean) => void;
}

export const useAppStore = create<AppState>((set) => ({
  isLoading: false,
  setIsLoading: (isLoading: boolean) => set({ isLoading }),
}));
```

--------------------------------

### Install Testing Dependencies

Source: https://github.com/shayancoin/paform/blob/main/docs/frontend-development.md

Commands to install necessary development dependencies for testing React components using Jest and React Testing Library. These libraries facilitate unit and integration testing of frontend components.

```bash
npm install --save-dev jest @testing-library/react @testing-library/jest-dom
```

--------------------------------

### Run FastAPI Backend with Docker

Source: https://github.com/shayancoin/paform/blob/main/backend/README.md

Starts the FastAPI backend using Docker, enabling hot-reloading. This command requires specific Odoo environment variables to be set.

```bash
ODOO_ADMIN_USER=admin ODOO_ADMIN_PASS=admin scripts/dev.sh be
```

--------------------------------

### Run Pytest Tests for Backend Application

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

Commands to execute tests using pytest. The first command runs all tests, while the second runs tests and generates a code coverage report for the 'api' and 'services' directories.

```bash
# Run all tests
pytest

# Run tests with coverage report
pytest --cov=api --cov=services
```

--------------------------------

### Build and Push Images to Container Registry with Docker Compose

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

Commands to build and push Docker images to a container registry using Docker Compose. This process requires the image names to be correctly configured in `docker-compose.yml` beforehand.

```bash
# Build the containers
docker compose --env-file .env.production -f docker-compose.yml build

# Push the containers
docker compose --env-file .env.production -f docker-compose.yml push
```

--------------------------------

### Run Paform Backend (FastAPI) without Docker

Source: https://github.com/shayancoin/paform/blob/main/README.md

This code illustrates how to set up and run the FastAPI backend service locally without using Docker. It involves navigating to the backend directory, creating and activating a Python virtual environment using `uv`, installing dependencies, and then running the uvicorn server.

```bash
cd backend
uv venv
source .venv/bin/activate
uv pip sync pyproject.toml
uvicorn backend.main:app --reload
```

--------------------------------

### Upgrade or Install PAForm Helm Chart

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

Deploys or updates the PAForm umbrella Helm chart. This command installs the chart into the 'paform' namespace, creating it if it doesn't exist, and uses a specified values file for configuration.

```bash
helm upgrade --install paform ops/helm/paform -n paform --create-namespace -f ops/helm/values-prod.yaml
```

--------------------------------

### Run Linting and Type Checking with Ruff and MyPy

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

Commands to perform code quality checks. 'ruff check .' runs the linter and formatter, while 'mypy .' performs static type checking on the project.

```bash
# Run ruff for linting
ruff check .

# Run mypy for type checking
mypy .
```

--------------------------------

### Install Helm Bootstrap Controllers

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

Applies the bootstrap controllers for Kubernetes using Helmfile. This is a crucial step after the cluster is provisioned to set up essential services like cert-manager and external-dns.

```bash
helmfile -f ops/k8s/bootstrap/helmfile.yaml apply
```

--------------------------------

### Installing OpenTelemetry Collector with Helm

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

This command deploys the OpenTelemetry Collector chart, which receives OTLP traces, generates span metrics, and forwards traces to Tempo. It requires a Tempo endpoint and can be configured with authentication headers via tempo.headers or a Kubernetes secret.

```bash
helm upgrade --install otel-collector ops/helm/otel-collector -n monitoring \
  --set tempo.endpoint="http://tempo.monitoring:4317"
```

--------------------------------

### FastAPI Endpoint for 3D Model Rendering

Source: https://context7.com/shayancoin/paform/llms.txt

An example FastAPI endpoint that accepts model ID and dimensions, generates a GLB file using `generate_cabinet_render`, and returns it as a FileResponse. This is useful for serving 3D models dynamically.

```python
from fastapi import FastAPI, Response
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/renders/{model_id}")
def get_render(model_id: str, width: float, height: float, depth: float):
    dimensions = {"width": width, "height": height, "depth": depth}
    glb_path = generate_cabinet_render(model_id, dimensions)
    return FileResponse(
        str(glb_path),
        media_type="model/gltf-binary",
        filename=f"{model_id}.glb"
    )
```

--------------------------------

### GitHub Actions Workflow Step for Deployment

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

A YAML snippet representing a step within a GitHub Actions workflow for deployment. This step depends on the completion of backend and frontend tests and is configured to run only on the main branch, executing custom deployment commands.

```yaml
deploy:
  needs: [backend-tests, frontend-tests]
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  steps:
    - uses: actions/checkout@v3
    - name: Deploy to production
      run: |
        # Add your deployment steps here
        echo "Deploying to production..."
```

--------------------------------

### Customize Resource Limits for a Docker Service

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

YAML snippet showing how to define resource limits (CPU and memory) for a specific service within a Docker Compose file. This allows control over the resources consumed by containers during deployment.

```yaml
services:
  backend:
    # ... other configuration
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
```

--------------------------------

### Add New API Endpoint in FastAPI

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

Example of adding a new asynchronous GET endpoint to a FastAPI application. This involves decorating an async function with a router method and defining its path and return type.

```python
from fastapi import APIRouter
from typing import Dict

router = APIRouter()

@router.get("/api/new-endpoint")
async def new_endpoint() -> Dict[str, str]:
    """New endpoint description.

    Returns
    -------
    Dict[str, str]
        Response data.
    """
    return {"message": "This is a new endpoint"}
```

--------------------------------

### POST /api/v1/pricing/preview - Advanced Pricing with Module Catalog

Source: https://context7.com/shayancoin/paform/llms.txt

Calculate a comprehensive pricing preview for multi-room projects using the internal pricing catalog. Supports module-level pricing, material selection, and project-level tax calculations. Requires Supabase authentication.

```APIDOC
## POST /api/v1/pricing/preview

### Description
Calculate a comprehensive pricing preview for multi-room projects using the internal pricing catalog. Supports module-level pricing, material selection, and project-level tax calculations. Requires Supabase authentication.

### Method
POST

### Endpoint
/api/v1/pricing/preview

### Parameters
#### Request Body
- **project** (object) - Required - Contains details about the project's rooms and modules.
  - **rooms** (array) - Required - An array of room objects.
    - **room_id** (string) - Required - The ID of the room.
    - **modules** (array) - Required - An array of module objects within the room.
      - **module_id** (string) - Required - The ID of the module.
      - **quantity** (number) - Required - The quantity of the module.
      - **material_id** (string) - Optional - The ID of the material for the module.
- **currency** (string) - Required - The currency for the pricing preview (e.g., "USD").

### Request Example
```json
{
  "project": {
    "rooms": [
      {
        "room_id": "kitchen-main",
        "modules": [
          { "module_id": "BASE-CAB-2DOOR", "quantity": 3 },
          { "module_id": "WALL-CAB-1DOOR", "quantity": 4 },
          { "module_id": "DRAWER-UNIT-4D", "quantity": 2, "material_id": "OAK-NATURAL" }
        ]
      },
      {
        "room_id": "kitchen-island",
        "modules": [
          { "module_id": "ISLAND-BASE", "quantity": 1 },
          { "module_id": "WATERFALL-PANEL", "quantity": 2, "material_id": "QUARTZ-WHITE" }
        ]
      }
    ]
  },
  "currency": "USD"
}
```

### Response
#### Success Response (200)
- **totals** (object) - Contains the calculated pricing totals.
  - **currency** (string) - The currency of the totals.
  - **subtotal** (number) - The subtotal amount.
  - **tax** (number) - The tax amount.
  - **total** (number) - The final total amount.
- **items** (array) - An array of items included in the pricing.
- **rounding** (object) - Information about currency rounding.
  - **currency** (string) - The currency for rounding.
- **guard** (object) - Placeholder for guard-related information.

#### Response Example
```json
{
  "totals": {
    "currency": "USD",
    "subtotal": 12450.00,
    "tax": 1120.50,
    "total": 13570.50
  },
  "items": [],
  "rounding": { "currency": "USD" },
  "guard": {}
}
```
```

--------------------------------

### Tailwind CSS Configuration Example

Source: https://github.com/shayancoin/paform/blob/main/docs/frontend-development.md

Example TypeScript configuration for Tailwind CSS, defining the content paths to scan for classes and extending the theme with custom colors. This file (`tailwind.config.ts`) is central to customizing the project's styling.

```typescript
import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: "#0070f3",
        secondary: "#1f2937",
      },
    },
  },
  plugins: [],
};
export default config;
```

--------------------------------

### Launch Supporting Docker Containers

Source: https://github.com/shayancoin/paform/blob/main/backend/README.md

Launches only the supporting Docker containers (Postgres and Odoo) for the development environment using a specific compose file and environment file. This is useful for isolating the database and Odoo services.

```bash
docker compose --env-file .env.development -f docker-compose.dev.yml --profile dev up -d
```

--------------------------------

### Initialize Terraform Modules

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

Initializes the Terraform working directory by downloading required providers and modules. This command does not create any resources and is a prerequisite for other Terraform operations.

```bash
make tf:init
```

--------------------------------

### GET /api/orders/{order_id} - Retrieve Order Details

Source: https://context7.com/shayancoin/paform/llms.txt

Fetch complete order information including customer details, line items, checkout preferences, and order totals.

```APIDOC
## GET /api/orders/{order_id}

### Description
Fetch complete order information including customer details, line items, checkout preferences, and order totals.

### Method
GET

### Endpoint
/api/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order to retrieve.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the order.
- **customer** (object) - Details about the customer.
- **items** (array) - List of items in the order.
- **checkout_url** (string) - The URL for the order checkout.
- **totals** (object) - Summary of order totals.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1-555-0123"
  },
  "items": [
    {
      "sku": "BASE-CAB-2DOOR-900",
      "quantity": 3,
      "price": 450.00
    }
  ],
  "checkout_url": "https://store.myshopify.com/checkout/abc123",
  "totals": {
    "subtotal": 1350.00,
    "tax": 108.00,
    "total": 1458.00
  }
}
```
```

--------------------------------

### GET /api/partcad/bom - Bill of Materials Retrieval

Source: https://context7.com/shayancoin/paform/llms.txt

Fetches the detailed bill of materials for a configured cabinet model. This BOM is used for downstream pricing calculations and manufacturing workflows.

```APIDOC
## GET /api/partcad/bom

### Description
Fetch the detailed bill of materials for a configured cabinet model, including component SKUs, quantities, and unit prices. The BOM drives downstream pricing calculations and manufacturing workflows.

### Method
GET

### Endpoint
/api/partcad/bom

### Parameters
#### Query Parameters
- **model** (string) - Required - The name of the cabinet model.
- **width** (float) - Required - The desired width of the cabinet in millimeters.
- **height** (float) - Required - The desired height of the cabinet in millimeters.
- **depth** (float) - Required - The desired depth of the cabinet in millimeters.
- **variant** (string) - Optional - Specifies the variant of the cabinet model (e.g., "flat-panel").

### Request Example
```bash
curl -X GET "http://localhost:8000/api/partcad/bom?model=wall-cabinet-1door&width=600&height=900&depth=350&variant=flat-panel" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200 OK)
- **model** (string) - The name of the cabinet model.
- **currency** (string) - The currency of the prices (e.g., "USD").
- **lines** (array) - An array of BOM line items.
  - **sku** (string) - The Stock Keeping Unit for the component.
  - **qty** (integer) - The quantity of this component.
  - **price** (float) - The unit price of the component.
  - **name** (string) - The name of the component.

#### Response Example
```json
{
  "model": "wall-cabinet-1door",
  "currency": "USD",
  "lines": [
    {
      "sku": "PANEL-PLY-18MM-600x900",
      "qty": 2,
      "price": 45.50,
      "name": "Side Panel 18mm Plywood"
    },
    {
      "sku": "DOOR-FLAT-600x720",
      "qty": 1,
      "price": 125.00,
      "name": "Flat Panel Door"
    },
    {
      "sku": "HINGE-EURO-SOFT",
      "qty": 2,
      "price": 8.75,
      "name": "European Soft-Close Hinge"
    }
  ]
}
```
```

--------------------------------

### Execute Paform Demo Script

Source: https://github.com/shayancoin/paform/blob/main/README.md

This bash script executes a pre-defined demo workflow for the Paform platform. It's designed to showcase the end-to-end functionality, likely involving the 3D asset viewing and pricing workflow.

```bash
scripts/demo.sh
```

--------------------------------

### Create and Reference Docker Swarm Secrets

Source: https://github.com/shayancoin/paform/blob/main/docs/docker-deployment.md

Bash command and YAML configuration for managing secrets in Docker Swarm. It shows how to create a secret from a string and then reference it within a service definition in `docker-compose.yml`.

```bash
# Create a secret
echo "my-secret-value" | docker secret create my_secret -

# Reference the secret in docker-compose.yml
secrets:
  my_secret:
    external: true

services:
  backend:
    secrets:
      - my_secret
```

--------------------------------

### Backend Environment Variables Configuration (Bash)

Source: https://context7.com/shayancoin/paform/llms.txt

This section lists essential environment variables for configuring the FastAPI backend services. It covers database connections (PostgreSQL, Redis), external service URLs (PartCAD, Odoo, Supabase), API credentials, and observability settings (OpenTelemetry, Prometheus). These variables are crucial for setting up the backend environment correctly.

```bash
# Database configuration
DATABASE_URL=postgresql://user:password@localhost:5432/paform
REDIS_URL=redis://localhost:6379/0

# PartCAD service configuration
PARTCAD_BASE_URL=http://partcad-service:5000
PARTCAD_CACHE_DIR=/var/cache/partcad
PARTCAD_RENDER_TIMEOUT=120
PARTCAD_BOM_TIMEOUT=30
PARTCAD_CACHE_MAX_BYTES=500000000
PARTCAD_CACHE_TTL_SECONDS=604800
PARTCAD_SAMPLE_GLB=frontend/public/kitchens/vvd/vvd.glb

# Shopify integration
SHOPIFY_STORE=mystore
SHOPIFY_TOKEN=shpat_your_admin_api_token
SHOPIFY_WEBHOOK_SECRET=your_webhook_secret

# Odoo ERP
ODOO_URL=http://odoo:8069
ODOO_DB=odoo
ODOO_USERNAME=admin
ODOO_PASSWORD=admin

# Supabase authentication
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_anon_key
SUPABASE_JWT_SECRET=your_jwt_secret

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
PROMETHEUS_METRICS_PORT=8000
```

--------------------------------

### Trigger Hygraph Sync Endpoints

Source: https://github.com/shayancoin/paform/blob/main/docs/backend-development.md

These POST requests are used to warm the Hygraph cache by triggering sync endpoints for materials, modules, and systems with a small page size. Ensure Redis is configured and accessible.

```bash
# Trigger sync for materials
POST /api/sync/hygraph/pull with {"type": "materials"}

# Trigger sync for modules
POST /api/sync/hygraph/pull with {"type": "modules"}

# Trigger sync for systems
POST /api/sync/hygraph/pull with {"type": "systems"}
```

--------------------------------

### Run k6 Load Test for Quote and CNC APIs

Source: https://github.com/shayancoin/paform/blob/main/tests/perf/README.md

This command executes a k6 load test against the quote generation and CNC export APIs. It configures environment variables for API base URLs, authentication tokens, request rate (RPS), duration, and virtual user (VU) pool sizing. The test targets approximately 500 RPS and enforces latency and error rate SLOs.

```bash
k6 run \
  --summary-trend-stats "avg,p(95),p(99),min,max" \
  -e API_BASE_URL="https://staging.api.example.com" \
  -e FRONTEND_BASE_URL="https://staging.fe.example.com" \
  -e API_WRITE_TOKEN="<token>" \
  -e RPS=500 \
  -e DURATION=5m \
  -e PRE_ALLOCATED_VUS=200 \
  -e MAX_VUS=600 \
  tests/perf/k6-quote-cnc.js
```

--------------------------------

### Retrieve Order Details (Bash)

Source: https://context7.com/shayancoin/paform/llms.txt

Fetches complete order information using a GET request to the /api/orders/{order_id} endpoint. It requires the order ID in the URL and an Accept header for JSON. The response includes nested details of the order.

```bash
# Retrieve a specific order
curl -X GET "http://localhost:8000/api/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Accept: application/json"
```

--------------------------------

### Deploying the Kubernetes Monitoring Stack with Helmfile

Source: https://github.com/shayancoin/paform/blob/main/docs/runbooks/deploy.md

This snippet demonstrates how to template and apply the kube-prometheus-stack release using helmfile. It manages the deployment of Prometheus, Alertmanager, and Grafana, and includes a paform-slo PrometheusRule for tracking API latency. Ensure ops/helm/monitoring/kps-values.yaml is updated for specific latency targets.

```bash
helmfile -f ops/helm/monitoring/helmfile.yaml template
# When ready to deploy
helmfile -f ops/helm/monitoring/helmfile.yaml apply
```

--------------------------------

### Docker Compose Configuration for Paform Development Environment

Source: https://context7.com/shayancoin/paform/llms.txt

This YAML file defines the services for the Paform development environment using Docker Compose. It specifies the frontend, backend, database, Redis, and PartCAD services, including their build configurations, port mappings, environment variables, volume mounts, and inter-service dependencies. This configuration is essential for running the Paform application locally.

```yaml
version: '3.8'

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
      - NEXT_PUBLIC_SHOPIFY_STORE=${SHOPIFY_STORE}
    volumes:
      - ./frontend:/app
      - /app/node_modules
    command: npm run dev

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/paform
      - REDIS_URL=redis://redis:6379/0
      - PARTCAD_BASE_URL=http://partcad:5000
    depends_on:
      - db
      - redis
    volumes:
      - ./backend:/app
    command: uvicorn backend.main:app --reload --host 0.0.0.0

  db:
    image: postgres:16.4
    environment:
      - POSTGRES_DB=paform
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  partcad:
    build:
      context: ./services/partcad
    ports:
      - "5000:5000"
    volumes:
      - partcad_cache:/cache

volumes:
  postgres_data:
  partcad_cache:

```

--------------------------------

### Build Next.js Application for Production

Source: https://github.com/shayancoin/paform/blob/main/docs/frontend-development.md

Command to build the Next.js application for production deployment. This command optimizes the application for performance and generates static assets and serverless functions in the `.next` directory.

```bash
npm run build
```

--------------------------------

### Calculate Advanced Pricing Preview (TypeScript)

Source: https://context7.com/shayancoin/paform/llms.txt

Calculates a detailed pricing preview for multi-room projects using the /api/v1/pricing/preview endpoint. It supports module-level pricing, material selection, and project-level tax calculations. Requires Supabase authentication and returns pricing totals and itemized details.

```typescript
import { apiClient } from '@/api/client';

interface PricingPreviewRequest {
  project: {
    rooms: Array<{ 
      room_id: string;
      modules: Array<{ 
        module_id: string;
        quantity: number;
        material_id?: string;
      }>;
    }>;
  };
  currency: string;
}

// Preview pricing for a complete kitchen project
const previewRequest: PricingPreviewRequest = {
  project: {
    rooms: [
      {
        room_id: "kitchen-main",
        modules: [
          { module_id: "BASE-CAB-2DOOR", quantity: 3 },
          { module_id: "WALL-CAB-1DOOR", quantity: 4 },
          { module_id: "DRAWER-UNIT-4D", quantity: 2, material_id: "OAK-NATURAL" }
        ]
      },
      {
        room_id: "kitchen-island",
        modules: [
          { module_id: "ISLAND-BASE", quantity: 1 },
          { module_id: "WATERFALL-PANEL", quantity: 2, material_id: "QUARTZ-WHITE" }
        ]
      }
    ]
  },
  currency: "USD"
};

const response = await apiClient.request(
  '/api/v1/pricing/preview',
  'POST',
  previewRequest
);

console.log(`Project Total: ${response.totals.currency} ${response.totals.total}`);
console.log(`Subtotal: ${response.totals.subtotal}`);
console.log(`Tax: ${response.totals.tax}`);

// Example response structure:
// {
//   "totals": {
//     "currency": "USD",
//     "subtotal": 12450.00,
//     "tax": 1120.50,
//     "total": 13570.50
//   },
//   "items": [...],
//   "rounding": { "currency": "USD" },
//   "guard": {}
// }
```

--------------------------------

### Create a New Page in Next.js App Router

Source: https://github.com/shayancoin/paform/blob/main/docs/frontend-development.md

Example of creating a new page component within the Next.js App Router structure. This involves creating a directory under `src/app` and adding a `page.tsx` file within it to define the page's content.

```tsx
export default function AboutPage() {
  return (
    <div className="container mx-auto py-8">
      <h1 className="text-2xl font-bold">About</h1>
      <p className="mt-4">This is the about page.</p>
    </div>
  );
}
```

--------------------------------

### Override PAplatform Helm Chart Values

Source: https://github.com/shayancoin/paform/blob/main/ops/helm/README.md

Demonstrates common overrides for PAplatform Helm charts using `--set` flags. These examples show how to modify image tags, resource requests, probe paths, and autoscaling bounds for individual services.

```bash
# Override image tag for backend
helm upgrade --install backend ops/helm/backend --set image.tag=backend-v1.2.3

# Override resource requests for a service
helm upgrade --install backend ops/helm/backend --set resources.requests.cpu=500m resources.requests.memory=1Gi

# Override readiness probe path
helm upgrade --install backend ops/helm/backend --set probes.readiness.path=/healthcheck

# Override autoscaling bounds
helm upgrade --install backend ops/helm/backend --set autoscaling.minReplicas=2 autoscaling.maxReplicas=10
```