Skip to content

spec-schema.md

Latest commit

 

History

History
182 lines (156 loc) · 9.11 KB

spec-schema.md

File metadata and controls

182 lines (156 loc) · 9.11 KB

App Forge — Canonical Spec Schema

This is the authoritative definition of the YAML app specification format. Every spec assembled by the wizard must conform to this schema before generation begins.

Complete Schema

# ==============================================================================
# APP FORGE SPECIFICATION SCHEMA v1
# ==============================================================================

meta:
  name: "string"           # Required. kebab-case, alphanumeric + hyphens only.
                            # Used for: directory name, package.json name, repo name.
                            # Example: "support-copilot", "invoice-extractor"
  description: "string"    # Required. One-line semantic intent.
                            # Used for: README header, LLM context during generation.
  stack: "nextjs" | "fastapi"  # Required. Compilation target.

# ------------------------------------------------------------------------------
# DATA & PERSISTENCE
# Generates: Prisma schema (Next.js) or SQLAlchemy models (FastAPI)
# ------------------------------------------------------------------------------
data:
  provider: "sqlite" | "postgres" | "none"  # Default: "none"
  models:                                     # Required if provider != "none"
    - name: "string"       # PascalCase entity name. Example: "User", "Invoice"
      fields:
        - name: "string"   # camelCase field name. Example: "orderNumber", "totalAmount"
          type: "string" | "integer" | "number" | "boolean" | "datetime"
          optional: boolean  # Default: false
          relation: "string" # Optional. References another model name for FK.
                             # Example: "User" on an Order.userId field

# ------------------------------------------------------------------------------
# AUTHENTICATION
# Generates: Auth.js config (Next.js) or FastAPI-Users/JWT setup (FastAPI)
# ------------------------------------------------------------------------------
auth:
  enabled: boolean          # Default: false
  methods:                  # Required if enabled: true
    - "email" | "google" | "github"

# ------------------------------------------------------------------------------
# AI AGENTS
# Defines intelligence layer, decoupled from UI.
# Each agent is referenced by routes via its id.
# Generates: Server Actions + AI SDK integration (Next.js)
#            or API endpoints + SDK calls (FastAPI)
# ------------------------------------------------------------------------------
agents:
  - id: "string"            # Required. Unique identifier. Example: "support_agent"
    system_prompt: "string"  # Required. Behavioral instruction for the LLM.
                              # Write as a directive, not a description.
                              # Include boundaries and refusal conditions.
    model: "string"          # Required. Concrete model string.
                              # Examples: "claude-sonnet-4-20250514", "gpt-4o",
                              # "llama-3.1-70b-versatile", "gemini-2.0-flash",
                              # "gemini-2.0-flash-lite", "gemini-1.5-pro"
    provider: "openai" | "anthropic" | "groq" | "google"  # Required. Determines SDK import.
    memory: "none" | "thread" | "rag"          # Default: "none"
      # none    → stateless. Every request is independent.
      # thread  → maintains message history array within a session.
      # rag     → retrieves context from a vector store before responding.
    thread_limit: integer    # Optional. Only relevant if memory: "thread".
                              # Max messages retained. Default: 20.

    structured_output:       # Optional. Define if agent returns typed data
                              # (not free-text). Compiles to Zod (Next.js) or
                              # Pydantic (FastAPI).
      - field: "string"     # Field name in the output object.
        type: "string" | "number" | "boolean"
        description: "string"  # Optional. Semantic hint for the LLM output prompt.

    tools:                   # Optional. External tools the agent can invoke.
      - name: "string"      # Tool function name. Example: "lookup_order"
        description: "string" # What the tool does. Injected into agent context.
        parameters:           # Key-value pairs: parameter_name → type
          "[key]": "string" | "number" | "boolean"

# ------------------------------------------------------------------------------
# ROUTES
# Maps URL paths to interaction patterns and agents.
# Generates: file-system routing (Next.js) or FastAPI route decorators (FastAPI)
# ------------------------------------------------------------------------------
routes:
  - path: "string"           # URL path. Example: "/", "/dashboard", "/chat"
    pattern: "string"        # Required. One of the interaction patterns below.
    requires_auth: boolean   # Default: false. If true, route is protected.
    agent: "string"          # Optional. References agents[].id.
                              # Required for: conversational, single_shot,
                              # batch_process, copilot, autonomous.
                              # Omitted for: observer (no agent needed).
    render_mode: "server" | "client"
      # Next.js only. Ignored for FastAPI stack.
      # server → async Server Component, no "use client" directive.
      #          Use for: observer pattern, static data display.
      # client → "use client" directive, client-side hooks allowed.
      #          Use for: conversational, single_shot, copilot, batch_process.
      # Default inference if omitted:
      #   conversational → client
      #   single_shot    → client
      #   batch_process  → client
      #   observer       → server
      #   autonomous     → server (no UI)
      #   copilot        → client

# ------------------------------------------------------------------------------
# ENVIRONMENT VARIABLES
# Generates: .env.example file with descriptions.
# Auto-derived from agents and auth config during wizard Step 6.
# ------------------------------------------------------------------------------
env_vars:
  - key: "string"            # Env var name. Example: "ANTHROPIC_API_KEY"
    description: "string"    # Human-readable explanation for .env.example comments.
    required: boolean         # Default: true.

# ------------------------------------------------------------------------------
# ERROR BEHAVIOR
# Defines how the app handles AI failures at the UX level.
# Generates: try/catch wrappers and user-facing error states.
# ------------------------------------------------------------------------------
error_behavior:
  ai_failure: "retry_once" | "show_error" | "fallback_message"
    # retry_once       → one retry with same params, then show_error.
    # show_error       → display a generic error message to user.
    # fallback_message → display the custom fallback_message string.
    # Default: "show_error"
  fallback_message: "string"  # Optional. Only used if ai_failure: "fallback_message".

Interaction Pattern Reference

Each pattern maps to specific architectural primitives in the generated code.

Pattern What It Generates (Next.js) What It Generates (FastAPI)
conversational useChat hook, streaming UI, message state array SSE streaming endpoint, Jinja2 chat template with HTMX
single_shot React Hook Form + Zod validation → Server Action HTML form → POST endpoint → result template
batch_process File upload component → async API route File upload → background task → results page
observer Async Server Component, direct DB query, data table Jinja2 template with DB query, auto-refresh via HTMX
autonomous No UI. Cron job or webhook API route only No UI. Background task / scheduled endpoint
copilot Sidecar panel with approval/reject buttons, suspended execution Inline approval form with HTMX, step-gated workflow

Validation Rules

Before generation, verify:

  1. meta.name is kebab-case, alphanumeric + hyphens only
  2. Every routes[].agent references a valid agents[].id
  3. If auth.enabled: true, at least one method is specified
  4. If data.provider != "none", at least one model is defined
  5. Every model field has a valid type
  6. No duplicate routes[].path values
  7. No duplicate agents[].id values
  8. render_mode is only set for stack: nextjs — ignore for FastAPI
  9. env_vars includes keys for all referenced providers and auth methods

Env Var Auto-Derivation Rules

The wizard should automatically populate env_vars based on the spec:

Spec Condition Generated Env Var
Any agent with provider: "openai" OPENAI_API_KEY
Any agent with provider: "anthropic" ANTHROPIC_API_KEY
Any agent with provider: "groq" GROQ_API_KEY
Any agent with provider: "google" GOOGLE_API_KEY
data.provider: "postgres" DATABASE_URL
auth.enabled: true AUTH_SECRET (session signing)
auth.methods includes "google" GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
auth.methods includes "github" GITHUB_ID, GITHUB_SECRET

SQLite does not require a DATABASE_URL — it uses a local file path.