name: app-platform-designer
version: 1.0.0
min_doctl_version: "1.82.0"
description: Transform natural language application descriptions into production-ready DigitalOcean App Platform specifications. Use when designing apps, creating app specs, generating deploy.template.yaml, or architecting multi-component applications.
related_skills: [deployment, networking, postgres, managed-db-services]
deprecated: false

App Platform Designer Skill

Transform natural language descriptions into production-ready App Platform specifications.

Primary question: "I want to build [description]. What should my App Platform architecture look like?"

Produces:
- .do/app.yaml — App Platform specification
- .do/deploy.template.yaml — Deploy to DO button (public repos)
- .env.example — Environment variable template

Quick Decision

What do you need?
├── Design new app from description → Workflow 1
├── Analyze repo and create spec → Workflow 2
├── Add Deploy to DO button → Workflow 3
└── Multi-environment setup → Workflow 4

Workflow 1: Natural Language → App Spec

Trigger: "I need a web app with [description]"

1. Gather requirements:
2. What does the app do?
3. Language/framework?
4. Database needs?

5. Background processing?

6. Decompose into components:

7. HTTP-facing → services
8. Background processors → workers
9. One-time/scheduled → jobs
10. Static frontends → static_sites

11. Data stores → databases

12. Generate spec with health checks, env vars, routing

13. Validate: doctl apps spec validate .do/app.yaml

Full guide: See architecture-patterns.md

Workflow 2: Analyze Repository → App Spec

Trigger: "Here's my repo, create an app spec"

Check for:
├── Dockerfile → Use dockerfile build
├── package.json → Node.js app
├── requirements.txt / pyproject.toml → Python app
├── go.mod → Go app
├── Multiple directories with above → Monorepo

Full guide: See component-types.md

Workflow 3: Deploy to DO Button

Trigger: "Add Deploy to DigitalOcean button"

Requirements: Public GitHub repository

1. Create .do/deploy.template.yaml (wraps spec in spec: key, uses git: block)
2. Add button to README

[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/OWNER/REPO/tree/BRANCH)

Full guide: See deploy-to-do-button.md

Opinionated Defaults

Component Summary

Full guide: See component-types.md

Pattern Selection

What are you building?
├── Simple app (1 service)? → Pattern 1
├── Frontend + API? → Pattern 2
├── Need background processing? → Pattern 3
├── Monorepo? → Pattern 4
└── Complex SaaS? → Pattern 5

Full patterns: See architecture-patterns.md

Quick Start: Single Service + DB

name: my-app
region: nyc

services:
  - name: web
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    http_port: 8080
    instance_size_slug: apps-s-1vcpu-1gb
    health_check:
      http_path: /health
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

databases:
  - name: db
    engine: PG
    production: false

Quick Start: API + Frontend

name: fullstack-app
region: nyc

services:
  - name: api
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    source_dir: /api
    http_port: 8080
    health_check:
      http_path: /health
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

static_sites:
  - name: frontend
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    source_dir: /frontend
    build_command: npm run build
    output_dir: dist
    envs:
      - key: VITE_API_URL
        scope: BUILD_TIME
        value: /api

databases:
  - name: db
    engine: PG
    production: false

ingress:
  rules:
    - match:
        path:
          prefix: /api
      component:
        name: api
    - match:
        path:
          prefix: /
      component:
        name: frontend

Environment-Portable Design

All code must work in: local dev, Docker Compose, AND App Platform.

// Portable port binding
const port = process.env.PORT || 3000
server.listen({ port, host: '0.0.0.0' })

Database Quick Reference

Full guide: See database-configuration.md

Environment Variables Quick Reference

Full guide: See environment-variables.md

Ingress (Routing)

ingress:
  rules:
    - match:
        path:
          prefix: /api
      component:
        name: api
    - match:
        path:
          prefix: /
      component:
        name: frontend

For advanced routing: See networking skill

Validation

doctl apps spec validate .do/app.yaml
doctl apps spec validate .do/deploy.template.yaml

Instance Sizes

Full list: See shared/instance-sizes.yaml

Reference Files

• component-types.md — Services, workers, jobs, static sites
• architecture-patterns.md — All 5 patterns with YAML
• environment-variables.md — Scopes, types, placeholders
• deploy-to-do-button.md — Template conversion, button HTML
• database-configuration.md — Dev vs managed, bindable vars

Shared References

• AppSpec-Reference.md — Field-level syntax, constraints
• instance-sizes.yaml — All instance sizes and pricing
• regions.yaml — Available regions
• bindable-variables.md — All bindable variable patterns

Integration with Other Skills

• → deployment: Deploy the generated app spec via GitHub Actions
• → devcontainers: Create local dev environment with prod parity
• → postgres: Advanced database configuration
• → networking: Custom domains, CORS, VPC
• → migration: Convert from other platforms