Frontend Spec Summary

Overview

This document served as the blueprint for the Angular frontend (Phase 13). It was written on 2026-02-25 when no frontend code existed yet. The backend was already live with 252 tests passing.

Stack

• Angular 19 (latest stable), standalone components
• Tailwind CSS for primary styling
• Angular Material for form fields, dialogs, tables
• ApexCharts via ngx-apexcharts for charts
• Reactive Forms only, OnPush change detection, ViewEncapsulation.None

Project Structure

The frontend lives at /home/claude/customers/marketplace/frontend/ and follows a feature-module architecture:

• core/ -- ApiService (HttpClient wrapper), AuthService (JWT), auth interceptor, auth guard
• shared/ -- reusable components (loading spinner, empty state, currency display), pipes (weight, percentage), common types
• features/ -- feature modules:
  • containers/ -- Container Fill Optimization (the primary specified page)
  • surplus/ -- Browse/select surplus items
  • dashboard/ -- Landing page

Container Fill Optimizer Page

The most detailed specification in the document. Route: /containers/fill.

Page Sections (Top to Bottom)

1. Item Selection Panel -- buyer dropdown (admin) or pre-filled (buyer portal), container type selector (20ft/40ft/40ft HC), searchable multi-select surplus item picker, "Get Fill Suggestions" button
2. Container Gap Visualization -- horizontal progress bar showing utilization percentage, color-coded (green >85%, yellow 50-85%, red <50%), gap callout in MT
3. Fill Suggestions Table -- sortable by compatibility score, columns for mill, paper type+GSM, width, grade, available quantity, can-fill quantity, price per MT, origin country, select checkbox
4. Freight Comparison Card -- side-by-side LCL (partial) vs. FCL (filled) comparison showing weight, shipping mode, freight cost, rate per MT, route, rate source
5. Savings Summary Banner -- extra product cost, freight savings, net savings (bold green/red), recommendation text

TypeScript Interfaces

Key interfaces specified:

• FillSuggestionsRequest -- surplus_item_ids, buyer_id, container_type, include_same_mill
• FillSuggestionsResponse -- container_gap, suggestions, freight comparisons, extra_product_cost, net_savings
• ContainerGap -- current_weight, max_payload, gap_mt, utilization_pct, is_full, needs_fill
• FillSuggestionItem -- surplus_item_id, mill_name, paper_type, gsm, width_mm, score, grade, price, origin
• FreightComparison -- lcl/fcl totals, rates per MT, savings, route, rate_source

Deployment Configuration

• Nginx: serves built Angular files from dist/marketplace/browser/ at /mvp/app/
• Base href: /mvp/app/
• Build command: ng build --base-href /mvp/app/
• No PM2 needed -- Angular compiles to static files served directly by nginx
• CORS: backend Django settings include https://b2bpaper.xdvu.com in allowed origins

Backend API Endpoints Referenced

Sources

• raw/articles/FRONTEND-SPEC -- full specification document with TypeScript interfaces and deployment config

Related

• wiki/concepts/four-layer-architecture -- the overall system architecture the frontend sits within
• wiki/summaries/progress-summary -- Phase 13 completion details
• wiki/summaries/status-summary -- current deployment status
• wiki/summaries/discoveries-summary -- frontend implementation notes and component architecture
• wiki/concepts/phases-0-to-13-recap -- where the frontend fits in the build timeline