{"id":35066686,"url":"https://github.com/itsbrianhughes/p2p-lifecycle-simulator","last_synced_at":"2026-05-01T20:31:07.946Z","repository":{"id":328874281,"uuid":"1117153654","full_name":"itsbrianhughes/p2p-lifecycle-simulator","owner":"itsbrianhughes","description":"Real-world Procure-to-Pay (P2P) lifecycle simulator modeling purchase orders, shipments, goods receipts, invoices, and 3-way matching with variance and exception handling for mid-market distributors and retailers.","archived":false,"fork":false,"pushed_at":"2025-12-15T23:04:50.000Z","size":461,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-29T01:34:01.906Z","etag":null,"topics":["accounts-payable","edi","fastapi","integration-engineering","invoice-matching","p2p","procure-to-pay","procurement","python","sqlite","supply-chain","three-way-match"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsbrianhughes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T22:56:57.000Z","updated_at":"2025-12-15T23:04:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itsbrianhughes/p2p-lifecycle-simulator","commit_stats":null,"previous_names":["itsbrianhughes/p2p-lifecycle-simulator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itsbrianhughes/p2p-lifecycle-simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrianhughes%2Fp2p-lifecycle-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrianhughes%2Fp2p-lifecycle-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrianhughes%2Fp2p-lifecycle-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrianhughes%2Fp2p-lifecycle-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsbrianhughes","download_url":"https://codeload.github.com/itsbrianhughes/p2p-lifecycle-simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrianhughes%2Fp2p-lifecycle-simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32512662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounts-payable","edi","fastapi","integration-engineering","invoice-matching","p2p","procure-to-pay","procurement","python","sqlite","supply-chain","three-way-match"],"created_at":"2025-12-27T11:31:58.431Z","updated_at":"2026-05-01T20:31:07.932Z","avatar_url":"https://github.com/itsbrianhughes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Real-World P2P Lifecycle Simulator\n\n\u003e Business-realistic Procure-to-Pay (P2P) simulator: PO → receipt → invoice → 3-way match with tolerance rules and exception handling—built to demonstrate how business workflows map to system integrations.\n\n---\n\n## Project Purpose\n\nThis simulator models the **complete Procure-to-Pay (P2P) lifecycle** as it operates in real-world businesses—independent of any specific ERP platform. It demonstrates practical knowledge of:\n\n- How companies manage vendor relationships and purchasing\n- How goods flow from order to receipt to payment\n- How financial controls prevent overpayment and fraud\n- How exceptions are detected and resolved in AP workflows\n- How data flows across purchasing, warehouse, and accounting systems\n\n**This is not a toy demo.** It reflects the business logic, data structures, and operational discipline found in mid-market distributors, retailers, wholesalers, 3PLs, and importers.\n\n---\n\n## Presales relevance (what this demonstrates)\n\nSolutions Engineers win trust by proving they understand the customer’s workflow—not just the product UI.\n\nThis simulator demonstrates how real businesses prevent bad outcomes:\n- Overpayment\n- Duplicate invoices\n- Missing receipts\n- Price/quantity variances\n- “It shipped but accounting can’t pay it” chaos\n\nIf you can explain **3-way match + exceptions** clearly, you can explain almost any business workflow clearly.\n\n---\n\n## Where integrations show up in this lifecycle\n\nEven without a specific ERP, the integration touchpoints are consistent:\n- PO creation (procurement system)\n- Shipment/ASN visibility (warehouse/logistics)\n- Receipt confirmation (inventory)\n- Invoice ingestion (AP / OCR / EDI / supplier portal)\n- Match + exception workflow (controls)\n- Payment + remittance (finance)\n\nThis repo models the data flow so it’s easy to explain how systems should connect.\n\n---\n\n## Discovery questions this workflow maps to\n\n- What’s your source of truth for POs—ERP, procurement tool, or EDI?\n- Do you require receipts before invoice approval?\n- What are your tolerance thresholds (price/qty)?\n- Who resolves exceptions—AP, receiving, procurement, or vendors?\n- What’s the cost of a mismatch (chargebacks, late fees, delayed shipments)?\n\n---\n\n## Who This Is For\n\n### Target Industries\n- **Distributors** managing high-volume SKU procurement\n- **Retailers** balancing inventory buys with tight margin controls\n- **Wholesalers** coordinating multi-vendor supply chains\n- **3PLs** receiving goods on behalf of clients with strict verification requirements\n- **Importers / Manufacturers** managing international shipments and invoicing complexity\n\n### Relevant Roles\nThis project demonstrates competency for:\n- **Integration Engineers** (EDI, API, middleware)\n- **EDI Consultants** (850/856/810 mapping and business rules)\n- **P2P Analysts** (procurement operations and exception management)\n- **ERP Implementation Specialists** (business process configuration)\n- **Fractional Consultants** supporting mid-market finance/supply chain teams\n\n---\n\n## Screenshots\n\n### System Overview\nBackend-driven Procure-to-Pay lifecycle simulator showing system readiness and workflow scope.\n\n![System Overview](screenshots/01-system-overview.png)\n\n### API Overview\nAPI-first P2P simulator designed for integration engineers, EDI consultants, and P2P analysts.\n\n![API Overview](screenshots/02-api-overview.png)\n\n### Procurement Flow (PO → ASN → Receipt)\nEndpoints demonstrating purchase order management, shipment notifications, and goods receipt processing.\n\n![Procurement Flow](screenshots/03-procurement-flow-endpoints.png)\n\n### Invoice \u0026 Verification\nVendor invoice ingestion and verification endpoints supporting downstream 3-way match and exception logic.\n\n![Invoice \u0026 Verification](screenshots/04-invoice-and-matching.png)\n\n---\n\n## The P2P Lifecycle (What We Simulate)\n\nThe Procure-to-Pay process is the backbone of vendor payment integrity. This simulator covers all major steps:\n\n### 1. **Purchase Order (PO) Creation**\n   - Buyer creates a PO specifying products, quantities, prices, and delivery terms\n   - PO is transmitted to the vendor (in real EDI workflows, this is an **850 transaction**)\n   - Status: `Open`\n\n### 2. **Vendor Ships Goods (ASN)**\n   - Vendor prepares shipment and sends an **Advanced Shipment Notice (ASN)**\n   - ASN includes SKU details, quantities shipped, tracking, and expected delivery\n   - In EDI workflows, this is an **856 transaction**\n   - Status: `In Transit`\n\n### 3. **Goods Receipt (Warehouse Receiving)**\n   - Warehouse receives the shipment and posts a **Goods Receipt (GR)**\n   - Actual quantities and condition are recorded\n   - PO status updates: `Partially Received` → `Received`\n   - This creates the foundation for invoice verification\n\n### 4. **Vendor Invoice Submission**\n   - Vendor submits an invoice for payment\n   - In EDI workflows, this is an **810 transaction**\n   - Invoice includes line items with SKU, quantity invoiced, and prices\n   - Status: `Pending` (awaiting verification)\n\n### 5. **3-Way Match (Invoice Verification)**\n   - System automatically compares:\n     - **PO** (what was ordered)\n     - **Receipt** (what was received)\n     - **Invoice** (what the vendor is charging for)\n   - Match criteria:\n     - Quantity invoiced ≤ Quantity received (within tolerance)\n     - Invoice price matches PO price (within tolerance)\n   - **If match succeeds** → Invoice status: `Matched` → ready for payment\n   - **If match fails** → Invoice status: `Blocked` → exception created\n\n### 6. **Exception Handling**\n   - Blocked invoices generate exceptions:\n     - **Price Variance**: Invoice price differs from PO price beyond tolerance (e.g., \u003e2%)\n     - **Quantity Variance**: Invoice quantity differs from receipt quantity beyond tolerance (e.g., \u003e5%)\n     - **Missing Receipt**: Invoice submitted before goods received\n     - **Over-Invoiced**: Vendor bills for more than was received\n   - Exceptions are reviewed by AP/Procurement teams\n   - Resolution options:\n     - **Resolve**: Correct the data (adjust invoice, post additional receipt, etc.)\n     - **Waive**: Approve the variance (with notes/approval)\n\n### 7. **Payment \u0026 Closure**\n   - Once matched or exceptions waived → Invoice status: `Approved`\n   - Payment is processed (not simulated in this MVP)\n   - Invoice status: `Paid`\n   - PO status: `Closed`\n\n---\n\n## Why 3-Way Matching Matters\n\n**3-way matching is the core financial control in P2P operations.**\n\nWithout it, companies risk:\n- Paying for goods never received\n- Paying incorrect prices\n- Duplicate invoicing\n- Vendor billing errors\n- Fraudulent invoices\n\n**How it works in practice:**\n\n| Document | Data Point | Purpose |\n|----------|-----------|---------|\n| **Purchase Order** | Authorized price \u0026 quantity | What we agreed to pay |\n| **Goods Receipt** | Actual quantity received | What we actually got |\n| **Invoice** | Vendor's bill | What vendor is charging |\n\nThe system compares all three. Mismatches = blocked payment until resolved.\n\n**Example Scenario:**\n- PO: 100 units @ $10.00 = $1,000\n- Receipt: 95 units received (5 damaged/missing)\n- Invoice: 100 units @ $10.00 = $1,000\n\n**Result:** Quantity variance exception → Invoice blocked → AP contacts vendor for credit memo or adjusted invoice.\n\nThis prevents overpayment and ensures tight financial controls.\n\n---\n\n## Technical Stack (and Why It's Lightweight)\n\nThis project intentionally uses a **minimal, transparent tech stack**:\n\n| Component | Technology | Rationale |\n|-----------|-----------|-----------|\n| **Backend** | Python + FastAPI | Readable, widely understood, minimal boilerplate. FastAPI provides auto-documentation and modern async patterns. |\n| **Database** | SQLite | Zero-config, portable, perfect for demonstrations. Shows schema design without deployment complexity. |\n| **Frontend** | HTML + Tailwind CSS (CDN) + Vanilla JS | No build tools, no frameworks, no abstractions. Focus stays on business logic, not React state management. |\n| **Data Format** | JSON | Industry-standard, human-readable, directly maps to EDI/API payloads. |\n\n**Why not a full-stack framework?**\n- This is a **business logic demonstration**, not a production SaaS product\n- The goal is to show **P2P process knowledge**, not mastery of Next.js\n- Lightweight = easy to read, easy to explain, easy to adapt\n- Portfolio reviewers can clone, run, and understand in minutes\n\n**This approach mirrors real integration work:**\n- Integration engineers work with data structures, business rules, and APIs\n- We translate between systems—understanding the business process matters more than UI polish\n\n---\n\n## Architecture Overview\n\n### Modular Design\nThe system is organized into clear, separated concerns:\n\n```\nPurchase Orders ──→ Shipment Notices (ASN) ──→ Goods Receipts\n                                                      ↓\n                                              ┌──────────────┐\n                                              │  3-Way Match │\n                                              │    Engine    │\n                                              └──────────────┘\n                                                      ↓\nVendor Invoices ────────────────────────────→ Match Records\n                                                      ↓\n                                              ┌──────────────┐\n                                              │  Exception   │\n                                              │    Engine    │\n                                              └──────────────┘\n                                                      ↓\n                                        Blocked Invoices / Resolutions\n```\n\n### Data Flow\n1. **POs** define expectations\n2. **ASNs** announce shipments (optional but realistic)\n3. **Receipts** record actuals\n4. **Invoices** trigger matching\n5. **Match Engine** compares PO ↔ Receipt ↔ Invoice\n6. **Exception Engine** detects and manages variances\n\n### Business Rules Configuration\nTolerance thresholds are configurable (not hardcoded):\n- Price variance tolerance: ±2%\n- Quantity variance tolerance: ±5%\n\nThese reflect real-world AP policies.\n\n---\n\n## Features Demonstrated\n\n### Core P2P Operations\n- ✅ Purchase Order creation with line-item detail\n- ✅ Advanced Shipment Notice (ASN) generation\n- ✅ Goods Receipt posting with quantity verification\n- ✅ Vendor Invoice ingestion\n- ✅ Automatic 3-way matching (PO ↔ Receipt ↔ Invoice)\n- ✅ Tolerance-based variance detection\n- ✅ Exception blocking and resolution workflows\n- ✅ Status tracking across the lifecycle\n- ✅ Audit trail visibility\n\n### EDI Concepts (Implicit)\nWhile this is not an EDI parser, it reflects EDI document structures:\n- PO → **850 Purchase Order**\n- ASN → **856 Ship Notice/Manifest**\n- Invoice → **810 Invoice**\n\nThe data models mirror how these documents are mapped in real integrations.\n\n---\n\n## What This Project Proves\n\nThis simulator demonstrates:\n\n1. **Business Process Expertise**\n   - Deep understanding of P2P workflows\n   - Knowledge of financial controls and AP best practices\n   - Awareness of distributor/retailer operational challenges\n\n2. **Data Modeling Skills**\n   - Clean, normalized relational schema design\n   - Proper foreign key relationships\n   - Realistic document structures\n\n3. **Integration Thinking**\n   - How data flows between purchasing, warehouse, and finance\n   - How documents reference each other (PO ↔ ASN ↔ Receipt ↔ Invoice)\n   - How exceptions interrupt automated workflows\n\n4. **System Design**\n   - Modular service architecture\n   - Separation of business logic from presentation\n   - Configurable rules and thresholds\n\n5. **EDI-Adjacent Knowledge**\n   - Understanding of 850/856/810 transaction purposes\n   - Ability to translate business requirements into data structures\n   - Readiness to work with EDI mapping and integration tools\n\n---\n\n## Quick Start\n\n### Prerequisites\n- Python 3.11+ (recommended: 3.12)\n- Modern web browser\n\n### Installation\n\n### 1. Clone the repository\ngit clone https://github.com/itsbrianhughes/p2p-lifecycle-simulator.git\ncd p2p-lifecycle-simulator\n\n### 2. Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n### 3. Install dependencies\npip install -r requirements.txt\n\n### 4. Run the application\npython -m backend.main\n\n### 5. Open your browser\n http://localhost:8000\n API docs: http://localhost:8000/docs\n\n\nThe application will:\n- Create the SQLite database automatically\n- Initialize all required tables\n- Serve the frontend on `http://localhost:8000`\n- Provide API documentation at `http://localhost:8000/docs`\n\n---\n\n## Project Structure\n\n```\np2p-lifecycle-simulator/\n├── backend/\n│   ├── main.py                    # FastAPI app + routes\n│   ├── database.py                # SQLite connection \u0026 initialization\n│   ├── schemas.py                 # Database table definitions\n│   ├── models.py                  # Pydantic data models\n│   ├── config.py                  # Business rules \u0026 constants\n│   └── services/                  # Business logic modules\n│       ├── po_service.py          # Purchase Order operations\n│       ├── asn_service.py         # Shipment Notice operations\n│       ├── receipt_service.py     # Goods Receipt operations\n│       ├── invoice_service.py     # Invoice operations\n│       ├── match_engine.py        # 3-way matching logic\n│       └── exception_engine.py    # Exception detection \u0026 handling\n│\n├── frontend/\n│   ├── index.html                 # Dashboard home\n│   ├── po.html                    # Purchase Orders UI\n│   ├── asn.html                   # Shipment Notices UI\n│   ├── receipt.html               # Goods Receipts UI\n│   ├── invoice.html               # Vendor Invoices UI\n│   ├── exceptions.html            # Exception Management UI\n│   ├── lifecycle.html             # P2P Lifecycle View\n│   └── js/                        # JavaScript modules\n│\n├── data/\n│   └── p2p.db                     # SQLite database (auto-generated)\n│\n├── docs/\n│   ├── ARCHITECTURE.md            # System design documentation\n│   ├── BUSINESS_RULES.md          # P2P business logic explained\n│   └── API.md                     # API endpoint documentation\n│\n├── requirements.txt               # Python dependencies\n└── README.md                      # This file\n```\n\n---\n\n## Use Cases\n\n### Business Application\n- Real-world Procure-to-Pay (P2P) lifecycle simulator modeling how mid-market distributors, retailers, and 3PLs manage purchasing, receiving, and vendor invoice verification.\n\n### As a Learning Tool\n- Study P2P workflows before an ERP implementation project\n- Understand how 3-way matching works in practice\n- Learn how EDI documents (850/856/810) relate to business processes\n- Practice explaining procurement operations to non-technical stakeholders\n\n---\n\n## Future Enhancements (Not in MVP)\n\nThis simulator focuses on core P2P logic. Potential extensions:\n\n- **Actual EDI Parsing**: Ingest 850/856/810 X12 or EDIFACT files\n- **Multi-Currency Support**: Foreign vendor invoicing\n- **Payment Processing**: Check runs and remittance advice (820)\n- **Returns \u0026 Credits**: Reverse logistics and credit memos\n- **Approval Workflows**: Multi-level PO authorization\n- **Reporting**: Aging reports, match rate analytics, vendor scorecards\n- **Integration APIs**: Connect to actual ERP/accounting systems\n\n---\n\n## About This Project\n\nThis simulator was built to demonstrate **real-world P2P operations knowledge** for integration engineering, EDI consulting, and business process roles.\n\nIt reflects the kind of business logic, financial controls, and data flows that mid-market companies rely on every day—independent of any specific ERP vendor.\n\n**Built by:** [Brian Hughes](https://github.com/itsbrianhughes/)\n**LinkedIn:** [https://www.linkedin.com/in/b-hughes/](https://www.linkedin.com/in/b-hughes/)\n\n---\n\n## License\n\nThis project is provided as-is for educational and portfolio purposes.\n\n---\n\n## Acknowledgments\n\nThis project draws on real-world procurement operations observed across distribution, retail, and logistics industries. It is designed to be teaching-oriented, business-realistic, and integration-focused.\n\n**Questions or feedback?** Open an issue or reach out directly.\n\n---\n\n**Ready to see P2P workflows in action? Run the simulator and explore the lifecycle.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsbrianhughes%2Fp2p-lifecycle-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsbrianhughes%2Fp2p-lifecycle-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsbrianhughes%2Fp2p-lifecycle-simulator/lists"}