Epic: Add tenant onboarding, examples, and end-to-end documentation

[patoperpetua]

Objective

Make PostKit adoptable by a new PoC or web application without requiring prior knowledge of this conversation or the internal architecture decisions.

This epic produces the onboarding path, reference integrations, local-development guidance, and end-to-end examples that prove the platform works for both backend services and marketing/web applications.

Required scenarios

Document and demonstrate at least:

1. PoC backend transactional email

Example: password reset or user invitation.

PoC backend
  -> @singleton-sd/post-kit-client
  -> PostKit API
  -> tenant template
  -> provider

2. Marketing-site Contact Us

The public browser posts to the marketing application's trusted server endpoint/server action.

Browser form
  -> marketing-site server endpoint
  -> @singleton-sd/post-kit-client
  -> PostKit

The browser must not contain the PostKit API credential.

3. Waitlist / whitelist signup

Show a web application sending an internal notification and/or confirmation email through PostKit using Git-backed templates.

4. Admin template editing

Show a React admin embedding @singleton-sd/post-kit-editor, editing EmailBuilder.js source files, previewing them, and saving through a consumer-controlled persistence adapter.

5. CI template publication

Show consumer repository templates being validated, compiled, and published to the correct tenant/environment location.

Tenant onboarding guide

A new tenant/PoC guide should answer:

• How is a tenant identifier chosen?
• How is the trusted consumer authenticated?
• Where is tenant branding configured?
• Where do source templates live in the consumer repo?
• How are templates compiled and published?
• How does the consumer install/use the npm client?
• How does an admin app install/use the editor?
• How are development/staging/production separated?
• How are sender addresses/provider configuration set up?
• How is a test email sent?
• How is a failed delivery diagnosed?

Recommended consumer structure

Document a standard convention such as:

consumer-app/
├─ content/
│  └─ email-templates/
│     ├─ marketing.contact-us/
│     │  ├─ template.json
│     │  ├─ metadata.json
│     │  └─ preview.json
│     └─ auth.password-reset/
│        ├─ template.json
│        ├─ metadata.json
│        └─ preview.json
├─ src/
└─ .github/workflows/
   └─ publish-email-templates.yml

Documentation expectations

Include:

• high-level architecture diagram
• monorepo/package ownership
• runtime request sequence
• template lifecycle sequence
• multi-tenant security model
• package installation and versioning
• local development
• Azure deployment/configuration
• template publishing
• troubleshooting
• contributing/releasing

Agent implementation notes

The documentation must match the implemented behavior, not just the intended architecture. Link directly to relevant package READMEs and example source.

Use singleton-sd/poc-plattform-kit as the reference for documentation style and consumer integration conventions where useful.

Examples should be minimal and executable/testable. Avoid creating large demo applications when small fixtures/examples can prove the integration.

Work

• Add root architecture documentation.
• Add tenant onboarding guide.
• Add API/client quick start.
• Add template-authoring guide.
• Add EmailBuilder editor integration guide.
• Add template publishing workflow guide.
• Add marketing Contact Us example.
• Add waitlist example.
• Add backend transactional-email example.
• Add environment/tenant configuration guide.
• Add security guidance for public web forms.
• Add operational troubleshooting guide.
• Add release/npm package usage documentation.
• Validate examples in CI where practical.

Acceptance criteria

• An agent or engineer unfamiliar with PostKit can onboard a new tenant using repository documentation alone.
• There is a working/reference marketing-site integration that does not expose PostKit secrets in the browser.
• There is a working/reference backend integration using @singleton-sd/post-kit-client.
• There is a reference admin integration using @singleton-sd/post-kit-editor.
• There is a documented Git-backed template lifecycle from edit -> PR -> CI -> Blob Storage -> send.
• Multi-tenant and environment boundaries are explained clearly.
• Documentation points to the Platform Kit only for shared conventions; PostKit-specific behavior is fully documented in this repository.