rapid-production

byShivi

BUILD A PRODUCTION-READY B2B SaaS CALLED “CBAM COPILOT”. ROLE: Act as a senior full-stack engineer, SaaS architect, compliance-tech expert and UI/UX designer. Build the REAL runnable application, not a mockup. GOAL: CBAM Copilot helps non-EU exporters and CBAM consultants: 1. Check whether products are covered by EU CBAM. 2. Estimate embedded emissions. 3. Estimate CBAM certificate exposure/cost. 4. Track assumptions and sources. 5. Generate professional PDF reports. 6. Preserve a complete audit trail. IMPORTANT: This is a compliance-support/estimation tool. It is NOT an official CBAM declaration, customs determination, legal advice or accredited verification service. MVP: Build only the following first: - Email/password authentication - Company profile - Client/importer profile - Shipment/product intake - Product/CN search - CBAM coverage engine - Emissions calculation engine - Default-value path - Actual-emissions path - Certificate-cost estimate - Carbon-price-paid-abroad input - Warnings - Audit trail - Assessment history - Professional PDF - Responsive dashboard - Automated tests Do NOT build Stripe, subscriptions, teams or consultant portfolio yet. Architect cleanly for them later. REGULATORY SOURCE OF TRUTH: Use CURRENT European Commission CBAM legislation, implementing/delegated regulations, official guidance and official datasets. CBAM definitive regime applies from 1 Jan 2026. Sectors: - Cement - Iron & steel - Aluminium - Fertilisers - Electricity - Hydrogen Importer/indirect customs representative has the importer-side CBAM obligations. Exporters/installations provide emissions information. Current mass-based threshold: 50 tonnes for relevant CBAM goods. Exporters may not know the importer's total EU aggregate quantity, so show threshold results as estimates unless confirmed by importer. NEVER INVENT REGULATORY VALUES. Reference data must be versioned: - Covered CN codes - Product descriptions - Sector - Emissions scope - Default values - Benchmarks - Methodology - Free-allocation parameters - Certificate prices - Other regulatory parameters Historical assessments must retain the exact reference-data version used. PRODUCT/CN ENGINE: Create a versioned CoveredGood table: cn_code, description, sector, covered, emissions_scope, default_value, methodology, effective_from, effective_to, source_version. Search by CN code, product name and keywords. Show matched CN, product, sector, coverage, emissions scope and warnings. Free-text classification must never be treated as authoritative. SHIPMENT INTAKE: User enters: company, importer/customer, origin, EU destination, shipment date, product, CN code, quantity, unit, production route, emissions data and carbon price paid abroad. Support multiple product lines. Show live totals: - Total quantity - CBAM-covered quantity - Embedded emissions - Estimated certificate exposure - Estimated cost A bad product line must produce a warning, not crash the whole assessment. EMISSIONS ENGINE: Support TWO paths. DEFAULT: Use the latest applicable official Commission default value. Store quantity, unit, value, source, reference version and result. ACTUAL: Allow installation/operator data: installation, production route, reporting period, direct emissions, indirect emissions where applicable, production quantity, intensity, evidence and verification status. Clearly distinguish default, actual and unverified data. Never claim “verified” without evidence/status. The Commission has corrected definitive-period default values in 2026, so data MUST be updateable/versioned and never permanently hardcoded. COST ENGINE: Calculate estimated exposure from applicable embedded emissions and certificate-price assumption. Certificate price: - Use latest official Commission price when available. - Allow manual override. - Always label it “Certificate price / planning assumption”. - 2026 uses quarterly prices. - From 2027 use weekly prices when officially published. - Never invent future prices. Allow carbon price paid abroad: amount, currency, period, evidence and status. Only deduct foreign carbon price when eligibility is established by current official rules. Otherwise show it as “Potential deduction — verification required”. REGULATORY FORMULAS: Implement current official EU formulas and parameters. Version every parameter. Never use fake placeholder values such as 1.0. If a required official parameter is unavailable, show “Calculation incomplete — official parameter unavailable”. AUDIT TRAIL: Every product calculation must retain: user inputs, CN match, coverage, sector, threshold assumption, emissions scope, data path, reference version, default value/source, actual emissions/source, formula, parameters, carbon price, certificate price, result and warnings. Historical calculations must NEVER silently change. DATABASE: Use PostgreSQL. Tables: Account User Client Assessment ProductLine CoveredGood ReferenceDataVersion EmissionsRecord CalculationAudit Report Use migrations, foreign keys, indexes and account-level isolation. BACKEND: Use FastAPI. Endpoints: POST /auth/register POST /auth/login GET /me GET/POST /clients GET/PUT /clients/{id} GET /products/search POST /assessments GET /assessments GET /assessments/{id} GET /assessments/{id}/audit POST /assessments/{id}/report GET /reports/{id} Validate all input server-side. FRONTEND: Use Next.js App Router, React, TypeScript, Tailwind CSS and Lucide. Design: Professional European compliance/industrial SaaS. Clean, calm, trustworthy. Deep-green accent, neutral background. Responsive mobile and desktop. Pages: Landing Login Register Dashboard New Assessment Results History Assessment Detail Settings RESULTS: Show: CBAM Covered Total Quantity Embedded Emissions Estimated Certificate Exposure Estimated Cost Product table: Product, CN, Sector, Coverage, Quantity, Emissions, Cost, Data source, Warnings. Add expandable “Why did we calculate this?” showing human-readable audit logic. PDF: Generate a professional server-side PDF containing: Cover Executive Summary Company/Importer Shipment Product-level assessment Embedded emissions Cost estimate Data sources Assumptions Warnings/missing data Audit trail Disclaimer Include “Prepared by CBAM Copilot”. Disclaimer: “This report is an analytical estimate and compliance-support document. It is not an official CBAM declaration, legal advice, customs determination or accredited verification report. Applicable requirements and data must be independently verified.” SECURITY: Use secure password hashing, secure authentication/session handling, account authorization, server-side validation, SQL injection protection, XSS-safe rendering, HTTPS-ready configuration, .env.example and no secrets in source code. PERFORMANCE: Product search <300ms. Normal calculation <5 seconds. PDF <10 seconds. TESTS: Test: - CN matching - Covered/uncovered products - Invalid CN - 50-tonne boundary - Default values - Missing default - Actual emissions - Direct/indirect emissions - Carbon price - Certificate price - Regulatory parameters - Audit trail - Historical calculation stability - PDF - Account isolation E2E: Register → Company → Assessment → Product → Calculate → Results → Audit → PDF. LANDING PAGE: Headline: “Know what CBAM could cost your exports — before your EU customer asks.” Subheadline: “Calculate CBAM exposure, document embedded emissions, identify missing data and generate a professional assessment in minutes.” CTA: “Create Free Assessment” SECONDARY CTA: “For Consultants” Do not promise guaranteed compliance. FUTURE ARCHITECTURE: Prepare extension points for: Stripe/subscriptions Google OAuth Multiple clients Consultant dashboard Team roles Custom branding Email delivery Supplier portal Supplier data requests Document/evidence management CSV/XLSX import ERP/customs integrations Compliance calendar Advanced analytics CRITICAL RULES: 1. Regulatory accuracy > feature quantity. 2. Never invent official CBAM values. 3. Version all regulatory datasets. 4. Never silently change historical calculations. 5. Explain every calculation. 6. Distinguish exporter support from importer obligations. 7. Never claim accreditation or verification. 8. Gracefully handle missing data. 9. Build a real runnable application, not a static demo. 10. Build MVP first. DEFINITION OF DONE: A new user can: Register → enter company → enter EU shipment → select/search product → enter quantity → determine CBAM coverage → calculate emissions → estimate cost → inspect assumptions/audit → generate PDF → reopen the same assessment later without its calculation changing. DELIVER: Complete runnable frontend + backend + PostgreSQL schema + migrations + calculation engine + versioned reference-data architecture + PDF generator + tests + README + environment configuration + production-ready folder structure.