[reemi01]

Summary

Updated and added vendor domain documentation and architecture documentation.

Related Issues

N/A

Requirement

N/A

Type of Change

• Documentation

What Changed

• Updated vendor management documentation.
• Added vendor onboarding documentation.
• Added ADR-0005 for vendor naming.
• Added vendor domain design documentation.
• Added the vendor domain design documentation under the docs root.

Design / Architecture

Documentation-only changes. ADR-0005 documents the vendor naming decision.

Testing

• Manual verification

Test Evidence

Reviewed the updated documentation files and verified that the changes are documentation-only.

Security / Data Isolation

• No cross-vendor data leakage introduced
• Authorization/policy behaviour verified
• Sensitive data handling reviewed
• Not applicable

Screenshots / Recording

Not applicable.

Documentation

• Documentation updated
• ADR added/updated if required

Reviewer Notes

Please review the vendor domain documentation, onboarding documentation, and ADR-0005 for consistency and naming.

Definition of Done

• No unrelated changes
• No secrets committed
• Self-review completed

[AdilAzhariOmsan]

Good first pass @reemi01. I can see that you worked through the domain rather than jumping straight into implementation, which is exactly what this task was intended to teach.

Before we approve the design, I want you to revisit a few areas where the proposal currently makes a reasonable conclusion but doesn't fully explain the invariant or trade-off behind it.

In particular, please clarify the Vendor creation boundary, whether the proposed lifecycle is genuinely complete, the distinction between lifecycle status and operating eligibility, the exact meaning of suspension, and how database constraints enforce the invariants you've identified.

🔴 Must resolve
Who creates a Vendor?
Why exactly these three lifecycle states?
What happens to rejected applications?
Is approved sufficient for operation?
What exactly does suspended block?
How is status constrained?
What does the deletion strategy actually mean?
Why is Security marked N/A?
What does "stable slug" mean?

I've left questions rather than corrections intentionally. Please respond to each question with your reasoning and revise the design where appropriate.

Do not start Task 2 or implementation work yet.

Once we've resolved these questions and the design is approved, we'll merge this PR and move to the next task.

[reemi01]

Thanks for the review. I revisited the design and addressed all of the requested points:

Vendor creation: A prospective Vendor submits an application, but submitting an application does not directly create a Vendor record. The Platform Operator controls Vendor creation through the Vendor management boundary.

Lifecycle states: pending, approved, and suspended represent the Vendor's operational lifecycle without mixing application outcomes with Vendor state

Rejected applications: A rejected application does not create a Vendor record and does not make the applicant eligible to operate.

Operating eligibility: approved is required but is not necessarily sufficient; other explicitly defined marketplace conditions may also apply.

Suspension: A suspended Vendor cannot perform normal seller operations or create new marketplace activity, while its identity and historical records are preserved.

Status constraints: The database should restrict status to pending, approved, or suspended, while the application/domain layer enforces valid transitions and authorization.

Deletion strategy: Deletion is not part of the Vendor lifecycle. Suspension preserves the Vendor and its historical relationships; any future deletion would be a separate data-management decision.

Security: The PR security section was updated to reflect that no cross-vendor data leakage is introduced by these documentation-only changes.

Stable slug:** The slug is a unique public identifier that remains unchanged during the Vendor's normal lifecycle, including approval, suspension, and reactivation.

The documentation and onboarding requirements were updated accordingly. No implementation or Task 2 work has been started.

[AdilAzhariOmsan]

If an application is accepted, does the Platform Operator explicitly create the Vendor record, or does accepting the application trigger Vendor creation? At what exact point does the pending state begin?

[AdilAzhariOmsan]

For a suspended Vendor, which of the following remain allowed: viewing historical orders, fulfilling existing orders, viewing historical earnings, editing existing products, creating new products, and receiving new orders? Please distinguish explicitly between blocked and permitted actions

[reemi01]

Thanks. I clarified both points in the design document.

For Vendor creation, the document now states that submitting an application does not create a Vendor record. The Platform Operator explicitly creates the Vendor after accepting the application, and the pending state begins when the Vendor record is created.

For suspended Vendors, the document now explicitly distinguishes permitted and blocked actions, including historical orders, existing order fulfillment, historical earnings, product editing, new product creation, and receiving new orders.