README

VPD Submission Returns Domain API - Project 0009

Proof-of-concept Domain API for Vaping Products Duty (VPD) Submission Returns.

Project Structure

.ai/projects/domain-apis/vaping-duty-domain-api/
├── README.md                   # This file
├── spec.md                     # Feature specification (WHAT to build)
├── plan.md                     # Implementation plan (HOW to build)
├── metadata.json               # Project metadata
├── domain-api.yaml             # Domain API OpenAPI spec (client-facing)
└── mocks/                      # Backend mock specifications
    ├── README.md
    ├── excise-api.yaml         # Excise duty system backend
    ├── customer-api.yaml       # Customer master data backend
    └── tax-platform-api.yaml   # Tax platform backend

OpenAPI Specifications

Domain API (Client-Facing)

File: domain-api.yaml Endpoint: /duty/vpd/submission-returns/v1

This is the unified API that clients interact with. It orchestrates calls to the three backend systems.

Key Features:

• POST to submit VPD returns
• GET by acknowledgementReference or approval+period
• Sparse fieldsets (fields[submission]=field1,field2)
• Idempotency via X-Idempotency-Key header
• ETag support for optimistic locking

Backend Mocks

Directory: mocks/

Three backend system specifications that the domain API orchestrates:

• excise - VPD registrations, periods, validation, calculations
• customer - Trader master data
• tax-platform - Submission storage and retrieval

See mocks/README.md for details.

Architecture

The Domain API orchestrates three backend systems:

Client
  ↓
Domain API
  ↓ ↓ ↓
excise  customer  tax-platform

POST Flow (Submit Return)

1. excise validates and calculates (returns customerId)
2. Parallel:
   • tax-platform stores submission
   • customer enriches response with trader details

GET Flow (By Acknowledgement)

1. tax-platform retrieves submission (includes customerId)
2. excise provides registration + period context
3. customer enriches with trader details

GET Flow (By Approval + Period)

1. excise validates access (returns customerId)
2. Parallel:
   • tax-platform finds submission
   • customer enriches with trader details

Backend Systems as Systems of Record

System	Owns	Provides
excise	VPD registrations, periods, duty rules	Validation, calculations, customerId bridge
customer	Trader master data	Names, types, addresses
tax-platform	Submissions, acknowledgements	Storage, retrieval, idempotency

Validation

# Validate domain API
redocly lint domain-api.yaml
 
# Validate backend specs
cd mocks
redocly lint excise-api.yaml
redocly lint customer-api.yaml
redocly lint tax-platform-api.yaml

Deployment Location

Once Phase 0 (specifications) is complete, these files will be deployed to:

repos/vaping-duty-poc/
├── domain-api/
│   └── specs/
│       └── vpd-submission-returns-api.yaml
└── mocks/
    └── specs/
        ├── excise-api.yaml
        ├── customer-api.yaml
        └── tax-platform-api.yaml

Related Documents

• Specification: spec.md - Complete feature requirements
• Plan: plan.md - Phase-by-phase implementation guide
• Codev Project: 0009 in workspace projectlist