ANDJJJJJJ/.kiro/specs/email-sorter-setup/design.md

Design Document

Overview

Das Email-Sortierer System besteht aus drei Hauptkomponenten:

1. Frontend: Vanilla JavaScript Multi-Step-Formular
2. Backend: Express.js Server mit API-Endpunkten
3. Datenbank: Appwrite Collections für Produkte, Fragen, Submissions, Antworten und Orders

Architecture

Browser (HTML/JS) 
    ↓ HTTP
Express Server
    ↓ API Calls
Appwrite Database
    
Express Server
    ↓ Webhook
Stripe Payment

Components and Interfaces

Frontend (public/index.html)

• Multi-step form renderer
• State management für Antworten
• API calls zu Backend

Backend (server/index.mjs)

• GET /api/questions - Lädt Fragen aus Appwrite
• POST /api/submissions - Speichert Kundenantworten
• POST /api/checkout - Erstellt Stripe Checkout Session
• POST /stripe/webhook - Empfängt Stripe Events

Bootstrap Script (server/bootstrap-appwrite.mjs)

• Erstellt Appwrite Database und Collections
• Erstellt alle Attribute/Spalten
• Seeded Produkt und 13 Fragen

Data Models

Products Collection

• slug: string
• title: string
• description: string
• priceCents: integer
• currency: string
• isActive: boolean

Questions Collection

• productId: string
• key: string
• label: string
• helpText: string (optional)
• type: string (text, email, select, multiselect, textarea)
• required: boolean
• step: integer
• order: integer
• optionsJson: string (optional)
• isActive: boolean

Submissions Collection

• productId: string
• status: string (draft, paid)
• customerEmail: email (optional)
• customerName: string (optional)
• utmJson: string (optional)
• finalSummaryJson: string
• priceCents: integer
• currency: string

Answers Collection

• submissionId: string
• answersJson: string

Orders Collection

• submissionId: string
• orderDataJson: string

Correctness Properties

Properties sind formale Aussagen über das Systemverhalten, die über alle gültigen Eingaben gelten.

Property 1: Question Loading For any active product, when questions are requested, all active questions for that product should be returned ordered by step and order. Validates: Requirements 1.1, 2.4

Property 2: Submission Creation For any valid answers object, when a submission is created, the system should store the submission and return a valid submissionId. Validates: Requirements 2.2, 2.3

Property 3: Payment Flow For any valid submissionId, when checkout is initiated, the system should create a Stripe session and return a checkout URL. Validates: Requirements 3.1, 3.2

Property 4: Webhook Validation For any Stripe webhook event, when the signature is invalid, the system should reject the request with 400 status. Validates: Requirements 3.4

Error Handling

• Fehlende Umgebungsvariablen → Server exit mit Fehler
• Ungültige Webhook-Signatur → 400 Bad Request
• Fehlende submissionId → 400 Bad Request
• Appwrite Fehler → Console error + graceful handling

Testing Strategy

Unit Tests:

• API endpoint responses
• Data validation
• Error handling

Property-Based Tests:

• Question ordering across random datasets
• Submission creation with various answer formats
• Webhook signature validation

Minimum 100 Iterationen pro Property Test.