type
concept
created
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
updated
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
sources
raw/articles/CHANGELOG, raw/notes/progress, raw/articles/CHECKLIST
tags
phases development timeline architecture build-history

Phases 0 to 13 Recap

abstract
A narrative summary of what each development phase delivered, from database schema (Phase 0) through Angular frontend deployment (Phase 13), building the complete Paper Surplus Marketplace MVP in approximately 4 days.

Build Timeline

The entire MVP was built between 2026-02-24 and 2026-02-27:

Phase-by-Phase

Phase 0: Data Models & Database Schema (P0)

The foundation. Created 13 entity models across 9 Django apps, all with UUID primary keys via a shared TimestampedModel base class. Key entities: Mill, Product, SurplusItem (with state machine), VisibilityRule, Buyer, BuyerSpec, MatchResult, ContainerProposal, IngestionBatch, ParserConfig, Newsletter, Transaction. All models have comprehensive field validation and indexed columns for query performance. 131 tests. Seed data fixtures created.

Phase 1: REST API Endpoints (P0)

Built 69+ REST API endpoints across 11 resource groups. Role-based permissions (admin, mill_user, buyer_user) on every endpoint. Swagger/OpenAPI documentation auto-generated. JWT authentication with login/refresh endpoints. 82 API tests.

Phase 1b: Excel Ingestion Pipeline (P0)

Four service modules handle the full ingestion lifecycle: file_processor.py (SHA-256 hashing, MIME/size validation, deduplication), parser.py (column alias resolution, unit conversion, paper type/grade lookup), validator.py (field-level validation with row-level errors), pipeline.py (status transitions, commit creates SurplusItems and triggers matching). Celery tasks for async processing and email polling (every 5 minutes). ~45 tests.

Phase 2: Data Bootstrap (P0)

Management commands for importing reference data: import_buyers and import_mills from CSV/JSON with deduplication, derive_specs (infers BuyerSpecs from transaction history), derive_products (infers Products from surplus history). All support --dry-run mode and generate import reports. ~14 command tests.

Phase 3: Matching Algorithm (P0)

Five scoring dimensions: paper type compatibility, GSM range match, width compatibility, quality grade match, and geographic proximity. Composite scoring with weighted averages produces an overall match score (0-100). Auto-triggers on SurplusItem create/update via signals. Full re-match benchmark included. 79 matching tests.

Phase 4: Geographic Visibility (P0)

VisibilityRule model with allow/deny rule types and scope hierarchy (region -> country -> city). Rules can be mill-wide defaults or per-surplus-item overrides. Price adjustments per rule allow regional pricing. The matching algorithm respects visibility: a buyer in a denied region never sees matches. 22 visibility tests.

Phase 5: Newsletter Generation (P0)

Per-buyer personalized newsletters containing visibility-filtered surplus matches. Tracking pixels for open detection, click tracking for link engagement. Bounce handling with automatic deactivation of invalid email addresses. Newsletter lifecycle: generated -> sent -> delivered -> opened -> clicked (or bounced/failed).

Phase 6: Container Assembly (P1)

Greedy bin-packing algorithm for filling containers (20ft, 40ft, 40ft HC). Freight cost estimation comparing LCL (less than container load) vs. FCL (full container load). Container proposal lifecycle: proposed -> accepted/modified/declined/expired. Fill suggestions API returns scored suggestions ranked by compatibility. 39 container tests.

Phase 7: Exclusivity Mechanism (P1)

Grant/release/try_next workflow for surplus items. 48-hour exclusivity windows: a buyer gets exclusive access to negotiate on a surplus item. Maximum 3 grants per item (if first two buyers decline, try a third). Auto-release on window expiry transitions the item back to available.

Phase 8: Pre-Production Announcements (P2)

Pre-production items with future availability dates. Auto-transition from pre_production to available status when the date arrives (via Celery beat). Express interest endpoint lets buyers signal demand before items become available. Foundation for the wiki/concepts/make-to-order-marketplace concept.

Phase 9: Remaining API Tests (P0)

Gap-filling test phase: role change endpoint tests, visibility rule CRUD tests, re-matching trigger endpoint tests, ingestion commit/reject action tests. Ensured comprehensive API coverage.

Phase 10: Admin Dashboard (P0)

Three dashboard views: admin (system-wide metrics), mill (own surplus, matches, transactions), buyer (own specs, matches, proposals). Key metrics surfaced for each role.

Phase 11: Security & Permissions (P0)

Audit logging for sensitive operations (model changes, authentication events). File upload validators (type whitelisting, size limits). RBAC enforcement verified across all endpoints. 29 security tests.

Phase 12: Acceptance Testing

Four integration tests covering full end-to-end flows (supply -> match -> offer -> close). 16 performance benchmarks: single scoring latency, batch scoring throughput, full re-match benchmark, per-item timing analysis.

Phase 13: Angular Frontend

Angular 19 + Tailwind CSS v4 + Angular Material 19. ~80+ component/service/route files. Role-based shell (admin sees all modules, mills see surplus/transactions, buyers see matching/transactions). JWT authentication with interceptor. Feature modules: dashboard, surplus, matching, transactions, newsletters, settings. Deployed at /mvp/app/ via nginx.

Post-Phase 13

Sources

Related