project:
  name: string
  type: app | agent | hybrid
  description: string (one sentence)

users:
  - role: string
    description: string
    count_estimate: string (range, e.g. "100-1,000 MAU")

frontends:
  - name: string
    type: <frontend_type>
    framework: string
    pages: [string]

services:
  - name: string
    type: <service_type>
    framework: string
    responsibilities: [string]
    endpoints: [string] (key endpoints only)

databases:
  - name: string
    type: <database_type>
    purpose: string (primary | cache | search | analytics | vector-store)
    key_collections: [string]

integrations:
  - name: string
    category: <integration_category>
    service: string (specific provider)
    purpose: string
    credentials: [string]

agents: (only for agent or hybrid projects)
  - name: string
    purpose: string
    llm_provider: <llm_provider>
    model: string
    orchestration: <agent_orchestration>
    interface: <agent_interface>
    tools:
      - name: string
        type: <agent_tool_type>
        description: string
    memory: session | persistent | vector-store
    guardrails: [string]

shared:
  types:
    - name: string
      description: string
      used_by: [string] (component names that share this type)
      fields: [string] (key fields or shape)
  libraries:
    - name: string
      purpose: string
      used_by: [string]
  contracts:
    - name: string
      type: api-schema | event-schema | proto-definition
      description: string
      between: [string] (component names)

application_patterns:
  architecture: <architecture_pattern>
  principles: [string] (e.g. "dependency inversion", "single responsibility")
  folder_convention: <folder_convention>
  error_handling: string (strategy description)
  testing_strategy: string (e.g. "unit + integration", "contract tests between services")

communication:
  - from: string (component name)
    to: string (component name)
    pattern: <communication_pattern>
    protocol: string (e.g. "HTTPS", "AMQP", "gRPC/Protobuf")
    auth: string (e.g. "JWT bearer", "API key", "mTLS", "none (internal)")
    data_format: string (e.g. "JSON", "Protobuf", "Avro")
    retry_strategy: string (optional, e.g. "exponential backoff, 3 retries")
    notes: string (optional, context for this connection)

artifacts:
  - name: string
    type: openapi | postman-collection | asyncapi | graphql-schema
    service: string (which service this artifact documents)
    format: yaml | json | graphql

security:
  auth_strategy: string (e.g. "JWT with refresh tokens via Clerk")
  api_security:
    - name: string (e.g. "rate limiting", "input validation", "CORS")
      implementation: string
      applies_to: [string] (component names)
  data_protection:
    encryption_at_rest: string (e.g. "AES-256 via database provider")
    encryption_in_transit: string (e.g. "TLS 1.3 on all endpoints")
    pii_fields: [string] (fields that contain personally identifiable information)
    data_retention: string (policy)
  secrets_management: string (e.g. "environment variables via Doppler / Vercel env")
  compliance: [string] (e.g. ["GDPR", "SOC2", "HIPAA"] — only if applicable)
  owasp_considerations:
    - threat: string (e.g. "SQL injection", "XSS", "CSRF")
      mitigation: string

observability:
  logging:
    strategy: string (e.g. "structured JSON logs")
    provider: string (e.g. "Axiom", "Datadog", "CloudWatch")
    log_levels: [string] (e.g. ["error", "warn", "info", "debug"])
  tracing:
    enabled: boolean
    provider: string (e.g. "OpenTelemetry → Jaeger" or "Datadog APM")
    instrumented_services: [string]
  metrics:
    provider: string (e.g. "Prometheus + Grafana", "Datadog")
    key_metrics: [string] (e.g. ["request latency p99", "error rate", "queue depth"])
  alerting:
    provider: string (e.g. "PagerDuty", "Opsgenie", "Slack webhooks")
    critical_alerts: [string] (e.g. ["error rate > 5%", "latency p99 > 2s", "queue backlog > 1000"])
  health_checks:
    - component: string
      endpoint: string (e.g. "/health")
      checks: [string] (e.g. ["database connectivity", "redis connectivity", "external API reachability"])

devops:
  cicd:
    provider: string (e.g. "GitHub Actions", "GitLab CI", "CircleCI")
    branch_strategy: <branch_strategy>
    pipeline_stages: [string] (e.g. ["lint", "test", "build", "deploy"])
    environments:
      - name: string (e.g. "development", "staging", "production")
        branch: string (e.g. "develop", "staging", "main")
        auto_deploy: boolean
        url_pattern: string (e.g. "{{service}}-dev.{{domain}}")
  database_migrations:
    tool: string (e.g. "Prisma Migrate", "Alembic", "Knex", "TypeORM")
    strategy: string (e.g. "versioned migrations with rollback scripts")
    seed_data: string (e.g. "dev seeds with faker data, staging seeds from anonymized prod")
    rollback_plan: string
  environment_config:
    strategy: <config_strategy>
    feature_flags: string (optional, e.g. "LaunchDarkly", "Unleash", "environment variables")
    config_validation: string (e.g. "Zod schema validation on startup")

deployment:
  - component: string
    target: string (e.g. "Vercel", "AWS ECS", "Railway")

project:
  name: "SupportBot Pro"
  type: hybrid
  description: "AI-powered customer support platform with human escalation"

users:
  - role: customer
    description: "End users seeking support"
    count_estimate: "1,000-10,000 MAU"
  - role: support-agent
    description: "Human support staff handling escalations"
    count_estimate: "5-20"
  - role: admin
    description: "Manages knowledge base, views analytics"
    count_estimate: "1-3"

frontends:
  - name: customer-widget
    type: web
    framework: React
    pages: [chat-widget, ticket-history]
  - name: agent-dashboard
    type: web
    framework: Next.js
    pages: [inbox, conversation-view, knowledge-base, analytics]

services:
  - name: api-server
    type: rest-api
    framework: Node.js/Express
    responsibilities: [auth, ticket-management, knowledge-base-crud]
  - name: agent-service
    type: websocket
    framework: Node.js
    responsibilities: [ai-agent-orchestration, streaming-responses]

databases:
  - name: primary-db
    type: postgresql
    purpose: primary
    key_collections: [users, tickets, conversations, knowledge_articles]
  - name: vector-db
    type: postgresql
    purpose: vector-store
    key_collections: [knowledge_embeddings]
  - name: cache
    type: redis
    purpose: cache
    key_collections: [sessions, rate_limits]

agents:
  - name: support-agent
    purpose: "Answer customer questions using knowledge base, escalate complex issues"
    llm_provider: anthropic
    model: claude-sonnet
    orchestration: react
    interface: chat-ui
    tools:
      - name: search-knowledge-base
        type: database-query
        description: "Vector search over knowledge articles"
      - name: create-ticket
        type: api-call
        description: "Create support ticket for human follow-up"
      - name: human-handoff
        type: human-handoff
        description: "Transfer conversation to human agent"
    memory: persistent
    guardrails:
      - "Never make promises about refunds or policy changes"
      - "Always disclose that you are an AI when asked"
      - "Escalate to human if confidence is low or customer is upset"

shared:
  types:
    - name: User
      description: "Core user type shared across API and dashboard"
      used_by: [api-server, agent-dashboard]
      fields: [id, email, role, displayName, createdAt]
    - name: Ticket
      description: "Support ticket shared between API, agent, and dashboard"
      used_by: [api-server, agent-service, agent-dashboard]
      fields: [id, customerId, subject, status, priority, messages[], assignedTo]
    - name: KnowledgeArticle
      description: "Knowledge base article used by API and AI agent"
      used_by: [api-server, support-agent]
      fields: [id, title, content, embedding, category, updatedAt]
  libraries:
    - name: shared-types
      purpose: "TypeScript type definitions shared across all Node.js services"
      used_by: [api-server, agent-service, agent-dashboard, customer-widget]
    - name: shared-validators
      purpose: "Zod schemas for request/response validation"
      used_by: [api-server, agent-service]
  contracts:
    - name: ticket-events
      type: event-schema
      description: "Event payloads for ticket lifecycle (created, assigned, resolved, escalated)"
      between: [api-server, agent-service]
    - name: api-contract
      type: api-schema
      description: "OpenAPI spec for the REST API consumed by frontends"
      between: [api-server, customer-widget, agent-dashboard]

application_patterns:
  architecture: clean-architecture
  principles:
    - "Dependency inversion — domain layer has zero external dependencies"
    - "Single responsibility — each service owns one bounded context"
    - "Interface segregation — clients depend only on the methods they use"
    - "Fail fast — validate at boundaries, trust internal data"
  folder_convention: feature-based
  error_handling: "Structured error codes with user-friendly messages. Services return {code, message, details}. Frontend maps codes to UI text."
  testing_strategy: "Unit tests for business logic, integration tests for API endpoints, contract tests between api-server and agent-service"

communication:
  - from: customer-widget
    to: api-server
    pattern: rest
    protocol: HTTPS
    auth: JWT bearer
    data_format: JSON
  - from: customer-widget
    to: agent-service
    pattern: websocket
    protocol: WSS
    auth: JWT bearer
    data_format: JSON
  - from: agent-dashboard
    to: api-server
    pattern: rest
    protocol: HTTPS
    auth: JWT bearer
    data_format: JSON
  - from: agent-service
    to: api-server
    pattern: rest
    protocol: HTTP (internal)
    auth: API key
    data_format: JSON
    notes: "Internal service-to-service call for ticket operations"
  - from: api-server
    to: agent-service
    pattern: message-queue
    protocol: Redis/BullMQ
    auth: none (internal)
    data_format: JSON
    retry_strategy: "exponential backoff, 3 retries"
    notes: "Async ticket assignment and AI processing"

security:
  auth_strategy: "JWT with refresh tokens via Clerk"
  api_security:
    - name: rate-limiting
      implementation: "Upstash Ratelimit — 100 requests/min per user"
      applies_to: [api-server]
    - name: input-validation
      implementation: "Zod schemas on all request bodies"
      applies_to: [api-server, agent-service]
    - name: cors
      implementation: "Whitelist customer-widget and agent-dashboard origins only"
      applies_to: [api-server]
    - name: helmet-headers
      implementation: "helmet middleware for CSP, HSTS, X-Frame-Options"
      applies_to: [api-server]
  data_protection:
    encryption_at_rest: "AES-256 via Supabase (PostgreSQL) default encryption"
    encryption_in_transit: "TLS 1.3 on all external endpoints"
    pii_fields: [email, displayName, phone]
    data_retention: "User data retained while account active, deleted 30 days after account deletion"
  secrets_management: "Vercel environment variables for production, .env files for local development"
  owasp_considerations:
    - threat: "Broken access control"
      mitigation: "Role-based middleware on every route. Support agents can't access admin endpoints."
    - threat: "Injection"
      mitigation: "Prisma parameterized queries. Zod validation on all inputs."
    - threat: "SSRF"
      mitigation: "Agent tool URLs whitelisted. No user-provided URLs fetched server-side."

observability:
  logging:
    strategy: "Structured JSON logs via pino"
    provider: "Axiom (free tier)"
    log_levels: [error, warn, info, debug]
  tracing:
    enabled: false
    provider: "Not needed at MVP stage"
    instrumented_services: []
  metrics:
    provider: "Vercel Analytics + Sentry performance"
    key_metrics: ["request latency p99", "error rate", "queue depth", "AI response time"]
  alerting:
    provider: "Sentry + Slack webhook"
    critical_alerts: ["error rate > 5%", "api-server down", "agent-service queue backlog > 500"]
  health_checks:
    - component: api-server
      endpoint: "/health"
      checks: ["PostgreSQL connectivity", "Redis connectivity"]
    - component: agent-service
      endpoint: "/health"
      checks: ["Redis connectivity", "Anthropic API reachability"]

devops:
  cicd:
    provider: "GitHub Actions"
    branch_strategy: github-flow
    pipeline_stages: [lint, test, build, deploy]
    environments:
      - name: staging
        branch: develop
        auto_deploy: true
        url_pattern: "{{service}}-staging.vercel.app"
      - name: production
        branch: main
        auto_deploy: true
        url_pattern: "{{service}}.vercel.app"
  database_migrations:
    tool: "Prisma Migrate"
    strategy: "Versioned migrations committed to git. Run automatically in CI before deploy."
    seed_data: "Dev seeds with faker.js for local development"
    rollback_plan: "Prisma migrate rollback for failed migrations. Manual SQL for data fixes."
  environment_config:
    strategy: env-vars
    feature_flags: "Environment variables (ENABLE_AI_AGENT=true/false) for MVP"
    config_validation: "Zod schema validates all env vars on service startup"