/component-discovery

name: component-discovery
description: Component type definitions, discovery questions, and settings validation for fullstack-typescript projects.
user-invocable: false

Component Discovery

Tech-specific discovery content for the fullstack-typescript tech pack. Loaded by the core `component-discovery` skill via `techpacks.routeSkills(phase: component-discovery)` to provide component type mappings, discovery questions, settings validation rules, and example configurations.

Core Discovery Questions

Use these questions to determine which component types are needed:

| Question | If Yes | Component Type | |----------|--------|----------------| | Do you need to persist data? | yes | `database` | | Does it have a backend/API? | yes | `server` | | Does the server expose an API consumed by other components? | yes | `contract` | | Does it have a user-facing frontend? | yes | `webapp` | | Will it be deployed to Kubernetes? | yes | `helm` (one per deployment mode) |

Component-Specific Discovery Questions

Once a component type is identified, ask deeper questions to understand scope and settings.

Backend (server + database)

External specs typically lack backend details. These must be derived from UI descriptions and explicit questions.

**YAGNI Principle**: Only derive operations explicitly shown in the UI. Do not assume full CRUD.

| Category | Discovery Question | Source | |----------|-------------------|--------| | **Entities** | What pieces of data need to be stored? | Look at what is displayed in the UI | | **Relationships** | What are the relationships between data? | Look at lists, dropdowns, links between views | | **User Actions** | What user actions modify data? | Look at buttons, forms, CTAs | | **Action Effects** | How does each action affect data? | Only operations visible in the UI | | **Business Rules** | What validation or constraints apply? | Often missing from specs -- verify or ask | | **Authorization** | Who can perform each action? | Often missing from specs -- verify or ask |

API Contract

Derive from UI analysis and ask clarifying questions:

| Category | Discovery Question | |----------|-------------------| | **Endpoints** | What operations are needed? List each with HTTP verb, path, and description. Only include operations visible in the UI. | | **Consumers** | Who calls this API? (webapp, mobile app, external service) | | **Error Cases** | What can go wrong? (validation errors, not found, unauthorized, conflicts) |

Frontend (webapp)

External specs usually have good UI detail. Extract rather than ask:

| Category | Discovery Question | Where to Find | |----------|-------------------|---------------| | **Pages/Views** | What screens does the user see? | Mockups, wireframes, user flow diagrams | | **Forms** | What data does the user input? | Form mockups, input field descriptions | | **States** | Loading, empty, error states? | May be missing from specs -- ask if absent |

Visual Assets Prompt

When UI/UX is involved and the spec does not include visual assets, ask:

Do you have any visual assets I can reference?
  - Mockups or wireframes (Figma, Sketch, etc.)
  - Screenshots of existing UI
  - Rough sketches or drawings
  - Reference images from other products

If you can share images, I can extract much more accurate
requirements than from text descriptions alone.

Skip this prompt if the spec already includes images or links to design tools.

Multiple Component Instances

Hybrid Servers

A single server can handle multiple processing modes. Ask:

Should the backend be a single service or multiple?
- Single API server
- API + Worker (hybrid mode in one deployment)
- Separate API and Worker servers (independent scaling)

• **Hybrid**: One server with `server_type: hybrid`, `modes: [api, worker]`
• **Separate**: Two servers, potentially two helm charts with different `deploy_modes`

Multiple Helm Charts per Server

A single server can have multiple helm charts for independent scaling:

• `order-service-api` with `deploy_modes: [api]` and `ingress: true`
• `order-service-worker` with `deploy_modes: [worker]` and `ingress: false`

This allows API and worker processes to scale independently.

Settings Validation

Before accepting the final component configuration, validate these cross-reference rules:

| Rule | Validation | |------|-----------| | **Database references** | Every database name in a server's `databases` array must exist as a `database` component | | **Contract references** | Every contract name in `provides_contracts` or `consumes_contracts` must exist as a `contract` component | | **Webapp contract references** | Every contract name in a webapp's `contracts` array must exist as a `contract` component | | **Helm deploy target** | Every helm chart's `deploys` value must reference an existing `server` or `webapp` component | | **Helm deploy modes** | A helm chart's `deploy_modes` must be valid for the target server's `server_type` (e.g., `[worker]` is only valid if `server_type` is `worker` or `hybrid` with `worker` in `modes`) | | **Config singleton** | Exactly one `config` component must exist |

Examples

Minimal Single-Server Project

components:
  - name: config
    type: config
    settings: {}
  - name: task-api
    type: contract
    settings:
      visibility: internal
  - name: task-db
    type: database
    settings:
      provider: postgresql
      dedicated: false
  - name: task-server
    type: server
    settings:
      server_type: api
      databases: [task-db]
      provides_contracts: [task-api]
      consumes_contracts: []
      helm: true
  - name: task-app
    type: webapp
    settings:
      contracts: [task-api]
      helm: true
  - name: task-server-chart
    type: helm
    settings:
      deploys: task-server
      deploy_type: server
      deploy_modes: [api]
      ingress: true
  - name: task-app-chart
    type: helm
    settings:
      deploys: tas