# 1. EXECUTIVE BUILD DIRECTION Build the product as a **modular monolith** using Next.js + Node.js/TypeScript with PostgreSQL as the primary system of record, Redis for asynchronous job coordination and short-lived operational state, Stripe for subscription billing, an external LLM API for content generation, and AWS managed services for deployment and document/object needs where required. **RECOMMENDATION — Architecture** Keep the web application, API, billing logic, workspace management, generation orchestration, usage enforcement, and persistence in one deployable application initially. Introduce a separate asynchronous worker process for AI-generation jobs because generation latency and external LLM availability should not block HTTP requests. Do not split into independently deployed microservices unless scale, ownership, deployment isolation, or reliability requirements later justify that complexity. Core implementation path: ACCOUNT + WORKSPACE FOUNDATION → AUTHORIZATION → PRODUCT DATA → GENERATION JOB MODEL → ASYNC WORKER → LLM INTEGRATION → SAVED OUTPUTS → USAGE ENFORCEMENT → STRIPE BILLING → OBSERVABILITY + FAILURE RECOVERY **STATUS:** READY WITH OPEN DECISIONS --- # 2. CONFIRMED REQUIREMENTS / INFERENCES / UNKNOWNS ## CONFIRMED REQUIREMENTS * AI-powered SaaS. * Generates: * marketing copy; * product descriptions; * social media posts. * Generation is based on customer product data. * Users require accounts. * Generated content must be saved. * Usage limits are required. * Team workspaces are required. * Subscriptions are required. * AI generation must operate asynchronously. * Next.js required. * Node.js + TypeScript required. * PostgreSQL required. * Redis required. * Stripe required. * External LLM API required. * Docker required. * AWS deployment required. * Engineering team size: four. * Managed services preferred. * Modular monolith preferred. ## JUSTIFIED INFERENCES * A user may belong to one or more workspaces. * Saved generations require durable persistence. * Generation requests need asynchronous lifecycle states. * Usage limits must be checked server-side before or during generation. * Stripe subscription state must affect generation entitlement. * AI generation requests require retry and failure-state handling. * Multi-user workspaces require server-side tenant isolation. * Product information should be persisted separately from generated content if users will reuse product data. ## RECOMMENDATIONS * Workspace should be the primary tenant boundary. * Separate generation request records from generation output records. * Use PostgreSQL for authoritative usage records rather than Redis. * Use Redis-backed queues for generation jobs. * Use Stripe webhooks as billing-state inputs while retaining application-side subscription state. * Maintain immutable or version-aware generation inputs where practical for reproducibility. * Start with role-based workspace authorization. ## UNKNOWNS * Authentication provider. * Exact subscription plans. * Exact usage-limit unit: * generations; * tokens; * credits; * words; * monetary spend. * Whether usage limits reset monthly or follow another period. * Workspace role hierarchy. * Whether users may belong to multiple workspaces. * Whether product records require images/files. * Whether generated content can be edited. * Whether generated content requires version history. * Supported social platforms. * Supported languages. * Prompt/template customization requirements. * LLM provider and models. * LLM cost ceilings. * Content moderation requirements. * Data retention requirements. * Regulatory requirements. * Required geographic region. * Required SLA/performance targets. --- # 3. SYSTEM BOUNDARY ## IN SCOPE Application responsibilities: * user authentication integration; * user profile lifecycle; * workspace lifecycle; * workspace membership; * role and permission enforcement; * subscription state; * product-data storage; * generation request creation; * generation job orchestration; * usage-limit checking; * LLM invocation; * generated-content persistence; * generation history; * failure handling; * billing webhook processing; * audit-relevant application events; * observability. ## OUT OF SCOPE Unless later required: * custom payment processing; * proprietary authentication implementation; * training or hosting foundation models; * full CRM functionality; * social-media publishing; * enterprise SSO; * custom distributed workflow engine; * multi-region active-active infrastructure; * independent microservices. ## EXTERNAL DEPENDENCIES * Stripe. * External LLM provider. * Authentication provider: UNKNOWN. * AWS infrastructure. * Email/notification provider if required: UNKNOWN. ## TRUST BOUNDARIES 1. Browser → application. 2. Application → PostgreSQL. 3. Application/worker → Redis. 4. Application → Stripe. 5. Worker → external LLM API. 6. Application/worker → AWS managed services. 7. Stripe → webhook endpoint. ## SYSTEMS OF RECORD **PostgreSQL** * workspaces; * memberships; * products; * generation requests; * outputs; * subscriptions; * usage ledger; * authorization-relevant state. **Stripe** * payment processor and external billing-event authority. **Redis** * queue and ephemeral processing state. Redis must not become the sole source of truth for subscription entitlement or consumed usage. --- # 4. ARCHITECTURE DECISION MAP ## DECISION A01 — Modular Monolith **EVIDENCE** Explicit preference plus four-person team. **WHY** Minimizes deployment, coordination, networking, and operational complexity. **TRADE-OFF** Less independent scaling and deployment isolation. **REVISIT TRIGGER** A module develops materially different scaling, reliability, ownership, or deployment requirements. --- ## DECISION A02 — Separate Async Worker **EVIDENCE** Asynchronous AI generation explicitly required. **WHY** LLM calls can be slow, rate-limited, or fail independently of user-facing HTTP requests. **TRADE-OFF** Introduces queue processing and eventual state transitions. **REVISIT TRIGGER** Generation becomes reliably synchronous within acceptable product latency. --- ## DECISION A03 — PostgreSQL as Primary Data Store **EVIDENCE** PostgreSQL explicitly required. **WHY** Core domain data is relational and transaction-sensitive. **TRADE-OFF** Not optimized for every future search or analytics workload. **REVISIT TRIGGER** Search, analytics, or throughput requirements exceed reasonable PostgreSQL capabilities. --- ## DECISION A04 — Redis for Queue + Ephemeral Coordination **EVIDENCE** Redis explicitly required and asynchronous generation exists. **WHY** Appropriate for transient job coordination, rate-limit state, and cache use. **TRADE-OFF** Requires resilience against eviction/restarts and reconciliation with durable records. **REVISIT TRIGGER** Job guarantees or scale require a stronger managed messaging platform. --- ## DECISION A05 — Managed AWS Services **EVIDENCE** Managed services preferred. **WHY** Reduces operational burden on four engineers. **TRADE-OFF** Higher provider coupling and potentially higher direct infrastructure cost. **REVISIT TRIGGER** Cost, portability, compliance, or scale materially changes priorities. --- # 5. FEATURE-TO-IMPLEMENTATION MATRIX | Feature | Frontend | API | Backend | Database | Integration | Authorization | Test | | ----------------- | ---------------------- | ------------------------ | ----------------- | --------------------- | ---------------- | ---------------------- | -------------------- | | Accounts | Login/account UI | Auth callbacks/profile | Identity module | User | Auth provider | User only | Authentication flows | | Workspaces | Workspace screens | Workspace endpoints | Workspace module | Workspace, Membership | — | Membership + role | Tenant isolation | | Products | Product editor | Product CRUD | Product module | Product | Optional storage | Workspace member | Ownership tests | | AI generation | Generation form/status | Generation endpoints | Generation module | GenerationJob | Redis + LLM | Entitled member | Async lifecycle | | Saved generations | History/detail UI | Output endpoints | Generation module | GenerationOutput | — | Workspace member | Cross-tenant denial | | Usage limits | Usage display | Usage endpoint | Usage module | UsageLedger | — | Workspace-scoped | Quota enforcement | | Subscriptions | Billing UI | Checkout/portal/webhooks | Billing module | Subscription | Stripe | Workspace billing role | Webhook tests | --- # 6. FRONTEND BLUEPRINT ## ROUTES Recommended: * `/login` * `/app` * `/app/[workspaceId]` * `/app/[workspaceId]/products` * `/app/[workspaceId]/products/[productId]` * `/app/[workspaceId]/generate` * `/app/[workspaceId]/generations` * `/app/[workspaceId]/generations/[generationId]` * `/app/[workspaceId]/team` * `/app/[workspaceId]/billing` * `/app/[workspaceId]/settings` ## SERVER STATE Use server-authoritative data for: * membership; * workspace roles; * subscription entitlement; * usage; * products; * generations; * job status. ## LOCAL STATE Use only for presentation-level state such as: * editor drafts; * filters; * open dialogs; * unsaved form input. ## REQUIRED UI STATES Generation: `IDLE → SUBMITTING → QUEUED → PROCESSING → COMPLETED` Failure variants: `FAILED_RETRYABLE` `FAILED_FINAL` `LIMIT_EXCEEDED` `SUBSCRIPTION_REQUIRED` Every async screen requires explicit loading and failure states. Authorization-sensitive controls may be hidden in the UI, but API authorization remains authoritative. --- # 7. BACKEND BLUEPRINT ## MODULE: Identity Responsibilities: * authenticated-user mapping; * user profile; * identity-provider linkage. --- ## MODULE: Workspace Responsibilities: * workspace lifecycle; * memberships; * invitations if later required; * roles. Enforces tenant ownership boundaries. --- ## MODULE: Product Responsibilities: * product-data CRUD; * workspace ownership; * generation-source preparation. --- ## MODULE: Generation Responsibilities: * request creation; * input snapshot; * generation type; * lifecycle state; * output persistence; * cancellation rules if supported; * generation history. --- ## MODULE: AI Provider Responsibilities: * provider adapter; * request transformation; * model configuration; * timeout; * error normalization; * response parsing; * token/cost metadata when supplied by provider. Provider-specific logic should not leak into core generation business rules. --- ## MODULE: Usage Responsibilities: * entitlement evaluation; * usage reservation; * final usage recording; * quota-period handling. Important operations should use transactions where concurrent generation requests could exceed limits. --- ## MODULE: Billing Responsibilities: * checkout session creation; * billing portal integration; * Stripe webhook processing; * Stripe customer mapping; * subscription-state synchronization. --- ## MODULE: Worker Responsibilities: 1. load durable job; 2. verify job state; 3. invoke AI provider; 4. persist result; 5. record usage; 6. transition job state; 7. retry eligible failures; 8. record terminal failure. --- # 8. DATA MODEL ## User Recommended fields: * `id` * `auth_provider_id` * `email` * `display_name` * `created_at` * `updated_at` Unique: `auth_provider_id` Potentially: `email` depending on identity-provider semantics. --- ## Workspace * `id` * `name` * `created_at` * `updated_at` Recommended: * `created_by_user_id` --- ## WorkspaceMembership * `workspace_id` * `user_id` * `role` * `created_at` Unique: `(workspace_id, user_id)` --- ## Product * `id` * `workspace_id` * `name` * `description` * `product_data` * `created_by_user_id` * `created_at` * `updated_at` `product_data` may initially use JSONB for flexible source attributes. --- ## GenerationJob * `id` * `workspace_id` * `product_id` * `created_by_user_id` * `generation_type` * `status` * `input_snapshot` * `provider` * `model` * `attempt_count` * `error_code` * `created_at` * `started_at` * `completed_at` Recommended statuses: * `QUEUED` * `PROCESSING` * `SUCCEEDED` * `FAILED` * `CANCELLED` --- ## GenerationOutput * `id` * `generation_job_id` * `content` * `provider_metadata` * `created_at` UNKNOWN: Whether multiple outputs belong to one generation job. --- ## Subscription * `id` * `workspace_id` * `stripe_customer_id` * `stripe_subscription_id` * `plan_key` * `status` * `current_period_start` * `current_period_end` * `updated_at` Unique: * `stripe_customer_id` * `stripe_subscription_id` where applicable. --- ## UsageLedger Recommended immutable ledger: * `id` * `workspace_id` * `generation_job_id` * `usage_type` * `quantity` * `period_key` * `created_at` Useful index: `(workspace_id, period_key)` --- # 9. API SPECIFICATION ## POST `/api/workspaces/:workspaceId/generations` **PURPOSE** Create asynchronous generation request. **AUTHORIZATION** Authenticated workspace member with generation permission. **INPUT** * product ID; * generation type; * generation options. **OUTPUT** `202 Accepted` ```json { "generationId": "...", "status": "QUEUED" } ``` **FAILURE STATES** * 400 invalid request; * 401 unauthenticated; * 403 unauthorized; * 404 product not available within workspace; * 409 conflicting request where applicable; * 429 usage exhausted or rate limited; * 503 queue unavailable. **IDEMPOTENCY NEED** Recommended. Client-generated idempotency key should prevent accidental duplicate generation requests. --- ## GET `/api/workspaces/:workspaceId/generations/:generationId` **PURPOSE** Retrieve job state and result. **AUTHORIZATION** Workspace membership plus resource ownership boundary. **OUTPUT** Job status and output when available. --- ## GET `/api/workspaces/:workspaceId/generations` Generation history. --- ## POST `/api/workspaces/:workspaceId/products` Create product. --- ## PATCH `/api/workspaces/:workspaceId/products/:productId` Update product. --- ## GET `/api/workspaces/:workspaceId/usage` Return current entitlement and consumed usage. --- ## POST `/api/workspaces/:workspaceId/billing/checkout` Create Stripe checkout session. Billing-management permission required. --- ## POST `/api/webhooks/stripe` Receive Stripe events. Authentication uses Stripe webhook signature verification rather than user authentication. Webhook processing must be idempotent. --- # 10. AUTHENTICATION & AUTHORIZATION ## AUTHENTICATION Exact provider: UNKNOWN. Recommendation: Use a managed authentication provider rather than implementing credential security directly. ## AUTHORIZATION Recommended initial roles: * OWNER * ADMIN * MEMBER Exact capabilities remain an OPEN DECISION. Authorization function should evaluate: `user + workspace + permission + resource ownership` Do not authorize solely from frontend route state or user-supplied workspace IDs. Example: ```text canGenerate(userId, workspaceId) ``` must verify active membership and generation entitlement server-side. Every product, generation, usage record, membership, and billing operation must enforce workspace isolation. --- # 11. RELIABILITY & FAILURE MATRIX | Failure | Impact | Detection | Recovery | Retry | User State | | ---------------------- | --------------------- | --------------------- | --------------------------------------- | --------------------------- | ------------------- | | LLM timeout | Generation delayed | Timeout metric | Retry job | Bounded exponential backoff | Processing/retrying | | LLM rate limit | Temporary failure | Provider response | Delayed retry | Yes, bounded | Queued/retrying | | LLM invalid response | Bad output | Validation | Retry or fail | Limited | Failed | | Redis unavailable | Jobs cannot dispatch | Health check | Restore queue + reconcile DB jobs | At enqueue layer | Temporary failure | | Worker crash | Job interrupted | Heartbeat/job timeout | Requeue/reconcile | Bounded | Processing | | PostgreSQL unavailable | Core app unavailable | DB monitoring | Managed recovery | Request-specific | Service unavailable | | Stripe webhook failure | Billing state delayed | Event processing logs | Stripe redelivery/manual reconciliation | Idempotent | Billing pending | | Network failure | External calls fail | Request telemetry | Backoff | Bounded | Temporary failure | No unlimited retry loops. Terminal failures require explicit persisted status. --- # 12. SECURITY BASELINE Required controls: * server-side authorization on every workspace resource; * strict tenant filtering; * schema validation for API inputs; * Stripe webhook signature verification; * secure secret management; * no LLM API keys exposed to clients; * bounded request sizes; * rate limiting where relevant; * output escaping; * secure session configuration; * audit logging for sensitive workspace and billing changes. ## SENSITIVE DATA Potentially includes: * customer product information; * generated proprietary marketing content; * billing identifiers; * membership information. Data classification requirements remain UNKNOWN. ## LLM DATA BOUNDARY OPEN DECISION: What customer data may be transmitted to the external LLM provider? This must be defined before production handling of sensitive customer information. --- # 13. OBSERVABILITY REQUIREMENTS Minimum metrics: * generation requests created; * queued jobs; * processing jobs; * completed jobs; * failed jobs; * generation latency; * queue wait time; * retry count; * LLM error rate; * LLM rate-limit responses; * usage-limit rejection count; * Stripe webhook failures. Structured logging should include correlation IDs: `request_id` `generation_id` `workspace_id` `job_id` Never log API secrets or unnecessarily expose user-generated sensitive content. --- # 14. IMPLEMENTATION TASK GRAPH ## T01 **LAYER:** Data **TASK:** Implement workspace-aware core schema. **DEPENDENCIES:** None. **PRIORITY:** P0 **DEFINITION OF DONE:** Users, workspaces, memberships, products, generation jobs, outputs, subscription state, and usage structures exist with migrations and core constraints. --- ## T02 **LAYER:** Security **TASK:** Implement authentication integration and workspace authorization middleware/services. **DEPENDENCIES:** T01 **PRIORITY:** P0 **DEFINITION OF DONE:** Authenticated identity can be mapped to workspace membership and unauthorized cross-workspace requests are rejected. --- ## T03 **LAYER:** Product **TASK:** Implement product-data CRUD. **DEPENDENCIES:** T01, T02 **PRIORITY:** P0 **DEFINITION OF DONE:** Authorized workspace users can persist and retrieve product data without tenant leakage. --- ## T04 **LAYER:** Generation **TASK:** Implement durable generation-job lifecycle. **DEPENDENCIES:** T01, T02, T03 **PRIORITY:** P0 **DEFINITION OF DONE:** Generation jobs transition through documented states and preserve request snapshots. --- ## T05 **LAYER:** Infrastructure **TASK:** Add Redis-backed job processing. **DEPENDENCIES:** T04 **PRIORITY:** P0 **DEFINITION OF DONE:** Queued generation IDs can be safely processed by a worker and duplicate execution is handled. --- ## T06 **LAYER:** Integration **TASK:** Implement LLM provider adapter. **DEPENDENCIES:** T05 **PRIORITY:** P0 **DEFINITION OF DONE:** Worker can invoke configured provider with timeout/error normalization and persist successful output. --- ## T07 **LAYER:** Usage **TASK:** Implement usage accounting and entitlement checks. **DEPENDENCIES:** T04 **PRIORITY:** P0 **DEFINITION OF DONE:** Concurrent requests cannot trivially bypass configured usage restrictions. --- ## T08 **LAYER:** Billing **TASK:** Integrate Stripe subscriptions. **DEPENDENCIES:** T01, T02, T07 **PRIORITY:** P1 **DEFINITION OF DONE:** Checkout, webhook synchronization, subscription persistence, and entitlement mapping operate idempotently. --- ## T09 **LAYER:** Frontend **TASK:** Implement generation workflow UI. **DEPENDENCIES:** T03-T07 **PRIORITY:** P1 **DEFINITION OF DONE:** Users can submit generation requests and observe queued, processing, success, and failure states. --- ## T10 **LAYER:** Operations **TASK:** Add observability and reconciliation processes. **DEPENDENCIES:** T04-T08 **PRIORITY:** P1 **DEFINITION OF DONE:** Failed/stuck generation and billing synchronization states are detectable. --- # 15. DEVELOPMENT SEQUENCE ### Phase 1 — Domain Foundation T01 → T02 → T03 Establish tenant boundaries before generation capability. ### Phase 2 — Generation Engine T04 → T05 → T06 Produce the first end-to-end asynchronous AI workflow. ### Phase 3 — Commercial Controls T07 → T08 Add enforceable usage and subscription state. ### Phase 4 — Complete Product Experience T09 Expose generation lifecycle cleanly to users. ### Phase 5 — Operational Hardening T10 + reliability/security validation. --- # 16. VALIDATION TEST PLAN ## TENANT ISOLATION Create: * User A / Workspace A; * User B / Workspace B. Verify User A cannot: * read Product B; * update Product B; * request generation against Product B; * view Generation B; * inspect Workspace B usage; * manage Workspace B billing. ## GENERATION LIFECYCLE Verify: `QUEUED → PROCESSING → SUCCEEDED` and: `QUEUED → PROCESSING → FAILED` Verify worker restart behavior. Verify duplicate job delivery does not create uncontrolled duplicate outputs or usage. ## USAGE ENFORCEMENT Test simultaneous requests near the usage boundary. PASS requires enforcement not to depend only on an eventually updated UI counter. ## STRIPE Test: * checkout event; * active subscription; * renewal; * cancellation; * failed payment where relevant; * duplicate webhook; * out-of-order webhook handling where practical. ## SECURITY Test: * forged workspace IDs; * unauthorized resource IDs; * malformed payloads; * missing authentication; * privilege escalation attempts; * invalid Stripe signatures. --- # 17. ARCHITECTURAL RISKS ## R01 — Undefined Usage Model **Impact:** HIGH The usage metric directly affects schema, billing, concurrency control, and customer entitlement. --- ## R02 — Undefined Workspace Roles **Impact:** MEDIUM Authorization implementation cannot be finalized without permissions. --- ## R03 — External LLM Data Handling **Impact:** HIGH Customer data may cross an external trust boundary. Retention and provider-processing policies must be established. --- ## R04 — Queue Durability **Impact:** MEDIUM If Redis is configured purely as volatile infrastructure, jobs may disappear without reconciliation. Durable PostgreSQL job records mitigate this. --- ## R05 — Billing/Usage Race Conditions **Impact:** HIGH Parallel generation requests may exceed quota unless reservation/accounting is transactional or otherwise concurrency-safe. --- # 18. OPEN DECISIONS **DECISION — Usage unit** RECOMMENDED — Define plans using an explicit internal credit unit mapped deterministically to chargeable operations. IMPACT — Required before final quota and subscription implementation. **DECISION — Authentication provider** RECOMMENDED — Managed authentication solution. IMPACT — Affects account lifecycle, session management, and team invitations. **DECISION — Workspace roles** RECOMMENDED — Start with OWNER / ADMIN / MEMBER. IMPACT — Required for authorization matrix. **DECISION — LLM provider/model** RECOMMENDED — Hide behind provider adapter. IMPACT — Prevents provider-specific behavior leaking into domain logic. **DECISION — AI input retention** RECOMMENDED — Persist the minimum generation snapshot needed for traceability and reproducibility. IMPACT — Affects privacy, storage, debugging, and generation history. --- # 19. BUILD-READY HANDOFF ## BUILD FIRST Implement the **workspace-aware domain schema and authorization boundary**. This unlocks products, generations, usage, subscriptions, and saved outputs while preventing tenant isolation from becoming a retrofit. ## DO NOT BUILD YET Do not build: * microservices; * Kubernetes; * dedicated search infrastructure; * multi-region architecture; * custom model hosting; * complex event streaming; * granular enterprise RBAC; * social-platform publishing. No supplied requirement currently justifies them. Do not finalize usage-accounting semantics until the quota unit and reset rules are defined. ## NEXT 5 ENGINEERING TASKS 1. Create PostgreSQL schema for users, workspaces, memberships, products, generation jobs, and outputs. 2. Implement authentication identity mapping and workspace authorization. 3. Implement workspace-scoped product CRUD. 4. Implement durable generation-job lifecycle and creation API. 5. Connect Redis worker execution to an abstract LLM provider adapter. ## VALIDATION GATE Before calling the architecture implementation-ready, obtain explicit decisions for: * authentication provider; * workspace roles; * subscription-plan entitlement model; * usage unit and reset period; * external LLM provider/model; * customer-data rules for LLM transmission and retention. The technical foundation can proceed before all six are resolved, but billing, authorization details, and production AI-data handling cannot be considered finalized without them. ## STATUS **READY WITH OPEN DECISIONS**