# initial_prompt.md

## AI Prompt for Web Application Development Workflow

The stack and constraints:
- Backend: Node.js v22, Express, TypeScript, Prisma (PostgreSQL 16), Zod, JWT, PM2, Jest, ts-jest
- Frontend: Next.js (React 18 + TypeScript), TailwindCSS, Axios.
- Auth: Google SSO + email/password, account migration from email → Google SSO, JWT authorization, credential encryption
- DB: PostgreSQL 16 in its own Docker container, Prisma ORM + Migrate
- Containers: Docker and Docker Compose (separate app and DB containers), persistent DB volume
- Scripts: start.sh waits for dependencies; shutdown.sh gracefully stops all containers
- Validation/formatting: Zod for runtime validation; Prettier for code formatting
- Process: Work in an existing Git repo; commit after each validated feature
- Roles: First registered user → ADMINISTRATOR; subsequent users → INTERVIEWEE; third role → INTERVIEWER. Admins can manage users/roles, and there must always be at least one ADMINISTRATOR. INTERVIEWER/INTERVIEWEE land on a welcome page. All pages include Logout.
- UI/UX: High-contrast dark mode; professional palette (#a30502, #f78b04, #2b1718, #153a42, #027f93); clean, readable typography; responsive layout; smooth animations/transitions; WCAG 2.2 compliant
- Secrets: Config files in /config; fallback to environment variables if missing
- Logging: Application logs + separate audit logs for ADMINISTRATOR/INTERVIEWER actions
- Resource/performance: Optimize container orchestration resources
- Documentation: Automatic generation (see Documentation Strategy)
- Observability: Add placeholders and TODO comments where Datadog monitoring will be integrated
- i18n readiness: Design architecture to be internationalization-ready for future expansion
- Use context7 mcp to consult latest documentation during implementation
- Test goals: 100% test pass rate and target 100% coverage; when not achievable, create TODO markdown of deferred tests

---

## 🎯 Objective

You are an expert AI web application developer and product manager. Generate a **comprehensive, production-ready implementation plan** for a modern full-stack TypeScript application with a Node.js + Express backend and a React 18 + Next.js frontend styled with TailwindCSS.
The plan must include **tasks, subtasks, and atomic tasks**, addressing **dependencies, edge cases, tests, rollback strategies, and documentation updates**.

The process should be **iterative**, **self-analyzing**, and **checkpoint-driven**, producing not just instructions but reflections and validations at each major phase. Actively perform self-analysis of your nature, choices, and reasoning as you plan and write. As you generate text (plans, designs, code, tests), refer to, interpret, and evolve your approach based on what you just wrote. This continuous meta-analysis must be explicit and actionable.

---

## 🧱 Core Tech Stack

### Frontend
- **Framework:** Next.js (React 18 + TypeScript)
- **Styling:** TailwindCSS
- **API Layer:** Axios for HTTP communication
- **Optional Tools:** Storybook for component documentation
- **Bundler:** Built-in Next.js

### Backend
- **Runtime:** Node.js 22+ (ESM, `"type": "module"`)
- **Framework:** Express (TypeScript)
- **ORM:** Prisma (PostgreSQL)
- **Validation:** Zod (source of truth for OpenAPI)
- **API Docs:** OpenAPI 3.1 → Redoc / Swagger UI

### Monorepo
- **Tooling:** Turborepo
- **Structure:**
  - `apps/web` → Next.js frontend
  - `apps/api` → Express backend
  - `apps/docs` → Docusaurus documentation site
  - `packages/ui`, `packages/shared` → shared components and utilities

---

## ⚙️ Database & Persistence

- **DB:** PostgreSQL 16
- **ORM:** Prisma ORM with migrations
- **Soft Deletes:** For user-generated content (`deleted_at`)
- **Indexes:** Partial indexes and partitioning for large tables
- **Pooling:** PgBouncer (local and prod)
- **Constraints:** Always ≥1 admin, transactional updates
- **Tuning:** WAL, shared buffers, autovacuum, and query analysis (EXPLAIN/ANALYZE)

---

## 🔒 Authentication & Authorization

- **Flows:** Email/password and Google SSO
- **Tokens:** Short-lived JWTs (5–10m) + refresh cookies (HTTP-only, Secure, SameSite=Lax)
- **Key Rotation:** JWKS endpoint with dual-key rotation
- **Roles:** ADMINISTRATOR, INTERVIEWER, INTERVIEWEE
- **Break-glass Recovery:** CLI-based superadmin
- **Rate Limits:** /auth and /api endpoints with per-IP/user quotas
- **CSRF:** Double-submit token pattern

---

## 🧰 API Design & Documentation

- **Zod-to-OpenAPI:** Zod schemas define API contracts.
- **Endpoints:** `/openapi.json` (machine-readable) + `/docs/api` (Redoc)
- **Versioned Docs:** Snapshot docs per release tag.
- **Docs CI/CD:**
  1. Generate OpenAPI JSON
  2. Run TypeDoc
  3. Build Docusaurus
  4. Publish versioned docs

---

## 🧪 Testing & Quality Gates

- **Unit/Integration:** Jest (ESM config)
- **E2E:** Playwright
- **Mutation Testing:** Stryker
- **Accessibility:** @axe-core/playwright (fails on WCAG 2.2 AA issues)
- **Visual Regression:** Playwright snapshots
- **Coverage Targets:** Global ≥90%, critical modules 100%
- **Deferred Tests:** Create TODO markdown for deferred/unimplemented tests

---

## 🩺 Runtime, Health, and Observability

- **Containers:** Single process per container
- **Health Checks:** `/healthz`, `/readyz` (checks DB, JWKS, migrations)
- **Metrics:** `/metrics` endpoint (Prometheus)
- **Observability Hooks:** `traceSpan()`, `metricCounter()`, `logContext()`
- **Secrets Management:** Cloud Secret Manager or Vault
- **CORS/TLS:** Strict enforcement and cookie hardening
- **TODO:** Add Datadog APM/trace TODO placeholders inline in code

---

## 🧭 Workflow and Feature Development Loop

Each feature must follow this loop before completion:

1. **Work Plan Creation**
   - Produce a high-level work plan broken down into:
   - Major tasks → subtasks → atomic tasks
   - Include for each task:
   - Acceptance criteria and objective success metrics
   - Quality gates (lint/typecheck/test/coverage thresholds)
   - Rollback triggers (explicit conditions to revert)

2. **UI/UX Planning and Approval**
   - Create UI/UX screenshot mockups for every page/feature BEFORE implementation.
   - **Element Identification**: Each visible element must have a clear element name or element ID in the screenshot for precise feedback and revisions.
   - **Multi-Step Workflows**: For features with multiple steps or states, provide a screenshot per step/state.
   - Support iterative refinement: accept feedback referencing element IDs/names and generate updated mockups.
   - Apply palette, dark mode, responsive layout, hierarchy, animations, and WCAG 2.2.
   - Do not proceed to implementation until UI/UX has been approved.

3. **Test Case Creation**
   - After approval, detail comprehensive frontend, backend, and E2E test cases.
   - Define pass criteria, coverage targets, test metrics.
   - Include security, accessibility, and performance tests where appropriate.
   - If tests cannot be fully implemented immediately, create a TODO markdown file listing deferred tests and rationales.

4. **Feature Development**
   - Backend: Express + TS + Prisma + Zod + JWT
   - Frontend: Next.js (React 18 + TS) + TailwindCSS + Axios + Vite
   - Implement with strict typing, runtime validation, secure API handling, error management.
   - use secure APIs and error handling.

5. **Testing & Rollback Plan**
   - Implement Jest, Playwright tests aiming for 100% coverage and pass.
   - If tests fail:
   - Fix iteratively until passing.
   - If persistent, ask to create a TODO markdown listing deferred tests and continue.
   - If app breaks after last working feature:
   - Use Git checkpoints or Git tags and impact assessment to rollback to stable state.
   - Refine the feature prompt and re-implement.

6. **Containerization & Optimization**
   - Use Docker multi-stage builds for app and database.
   - Apply resource and performance optimization strategies (CPU/memory limits in compose/yaml).
   - Provide start.sh that waits for all dependencies (DB Healthy), and shutdown.sh for graceful termination.
   - Use Docker Compose.

7. **Database Schema & Optimization**
   - Define schemas with Prisma, use migrations.
   - Follow PostgreSQL best practices:
   - Normalized schemas, indexed columns per query pattern.
   - Use appropriate data types and constraints, foreign keys, and soft deletes selectively.
   - Indexing strategies: B+ trees, GIN for JSONB, partial indexes.
   - Partition large tables by time or domain if applicable.
   - Ensure data durability with persistent volumes.

8. **Authentication & Role Migration**
   - Support email/password and Google SSO login.
   - Implement a migration workflow:
   - User initiates account migration.
   - Only complete if Google SSO auth succeeds.
   - If an existing SSO account exists, prompt merge.
   - Perform atomic migration, with rollback on error.
   - Log all steps and outcomes.
   - Enforce roles:
   - First user → ADMINISTRATOR
   - Later users → INTERVIEWEE, INTERVIEWER.
   - Admins manage users/roles via admin page, maintaining at least one admin.
   - Landing pages for interviewee/interviewer.

9. **Secrets, Configuration**
   - Config files stored in `/config`; fallback to environment variables if files missing.
   - Secure handling; no secrets baked into images.

10. **Logging & Audit**
   - Structured JSON logs with correlation/request IDs.
   - Application logs + audit logs for all moderator/admin actions.
   - Redact PII; configure log levels.

11. **Commit Strategy**
   - Commit after each feature/validation step.
   - Use conventional commits.
   - Tag releases at stable points.

12. **Documentation & Monitoring Placeholders**
   - Generate API docs (OpenAPI + Redocly or alternatives), TypeDoc, and Docusaurus docs site.
   - Automate docs updates via CI.
   - TODO placeholders for Datadog instrumentation in code:
   - APM trace setup
   - Metrics endpoints
   - Log enrichment
   - Placeholder health endpoints at `/healthz`, `/readyz`.

13. **Internationalization (i18n)**
   - Architecture prepared for multi-language support:
   - Configured locales in Next.js
   - Message catalogs; ICU formatting
   - Design for text expansion, RTL support
   - URL schemas for localized paths
   - Current only English; ready for future expansion.

14. **Deployment Configurations**
   - Local Docker Compose setup:
   - Multi-stage Dockerfiles for app and Postgres
   - Persistent Postgres volume
   - start.sh / shutdown.sh scripts
   - AWS:
   - ECR, Terraform templates
   - ECS Fargate / EKS options
   - Secrets: AWS Secrets Manager / Parameter Store
   - Monitoring placeholders (TODO for Datadog)
   - GCP:
   - Artifact Registry, Cloud Run / GKE
   - Cloud SQL for PostgreSQL
   - Azure:
   - ACR, Container Apps or AKS
   - Azure Database for PostgreSQL
   - Secrets via Key Vault
   - Multi-cloud considerations:
   - Standardize images, use environment-specific configs, IaC templates.

15. **Container Optimization & Security**
   - Use multi-stage Docker builds.
   - Run containers non-root.
   - Apply resource limits; health checks; update scanning.
   - Secrets injected at runtime securely.

16. **Security & JWT**
   - Short-lived tokens, refresh tokens.
   - Secure cookies, CSRF protections.
   - Rate limit login endpoints.
   - Maintain JWT key rotation strategy.


---

## 🧠 Self-Analysis Protocol

After each major step, perform a brief reflective evaluation:
- Identify 2–3 **risks or weaknesses** in approach.
- Compare **alternative strategies**.
- Record **decision rationale** and potential downstream impact.
- Maintain decision log for traceability.

---

## 🔁 Rollback & Recovery

- Use Git tags as stable checkpoints.
- Conduct impact analysis before rollback.
- Prefer partial rollback (component-level) before full revert.
- Document causes, fixes, and revalidation notes.

---

## 🧾 Definition of Done (DoD)

- [ ] Lint & Typecheck clean
- [ ] All tests pass
- [ ] Coverage ≥90%
- [ ] Accessibility checks pass
- [ ] Docs updated
- [ ] Observability hooks added
- [ ] Audit logs validated
- [ ] Rollback strategy documented

---

## 📄 Documentation Strategy

- Generate:
  - OpenAPI spec + Redocly site
  - TypeDoc code reference
  - Docusaurus guides/tutorials
- CI Integration:
  - Auto-build on merge
  - Version docs per tag
  - Publish to `docs.example.com`

---

## 🌐 Internationalization (i18n)

- **Routing:** Next.js i18n routing
- **Localization:** ICU format messages (`@formatjs`)
- **RTL:** Tailwind config for RTL support
- **Expansion:** Plan for additional locales and path schemas

---

## 🚀 CI/CD & Deployment

- **Pipeline:** GitHub Actions or GitLab CI
- **Stages:** install → build → test → docs → deploy
- **Environments:** staging (on PR merge) and production (on tag)
- **Cloud Options:** AWS ECS/GKE/Cloud Run with IaC templates
- **Secrets:** Managed by Secret Manager or Parameter Store
- **Monitoring:** TODO placeholders for Datadog, Prometheus

---

## 🧩 Additional Guidelines

- Follow **12-factor app** principles (no config files in repo)
- Enforce **security linting** (`eslint-plugin-security`)
- Use **feature flags** for incremental rollout
- Apply **Renovate or Dependabot** for dependencies
- Maintain **audit logs** with correlation IDs
- **Never store secrets in images**

---

## 📘 Output Requirements

The generated plan must include:
1. Phases & milestones (setup → deployment)
2. Tasks, subtasks, atomic tasks with dependencies
3. Edge cases, rollback paths, and fallback strategies
4. Required files & configuration snippets
5. Commit checkpoints & changelog references
6. Cross-linked docs and self-analysis checkpoints

---

### Final Notes
- All steps must have clear acceptance criteria.
- Use iterative refinement: mockups, tests, configs.
- Documentation and code must comply with latest standards.
- Self-reflection and pattern recognition enhance decision quality.

---

### End of initial_prompt.md