@awesomate/hosting-mcp/skill/awesomate-app-builder/references/stack-decision.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# Stack decision — match the tech to the job

Bias toward whatever **loads fastest and is the least machinery** for the need.
Ask at most 2–3 plain questions, then recommend a stack in one sentence and
confirm before building. **Never default to WordPress.**

## The map

| What the user is really trying to do | Stack | Why / how |
|---|---|---|
| "I already have a WordPress site" / a blog / publishes content regularly / **wants to rank on Google & AI** | **WordPress** | Best CMS for indexable content, sitemaps, schema. Hand to the awesomate-hosting skill to provision, then run **awesomate-seo**. Existing WP elsewhere → migrate it, don't rebuild: [wp-migrate.md](wp-migrate.md) (also covers WP ↔ app coexistence on subdomains). |
| Sell products / online shop | **WordPress + WooCommerce** | Provision via the awesomate-hosting skill, install WooCommerce over WP-CLI, then run **awesomate-seo** (product pages need `Product` JSON-LD + real product data). |
| A landing page / capture leads / a one-pager / "just needs to look good and be found" | **static site** (`kind: 'static'`) | Served straight from the cPanel docroot — no database, no server process, fastest load. Add SEO + a lead form (below). The right default for marketing pages — but see the three limits under the table before you commit to it. |

**What a static site cannot do** (the stack can't be changed later, so check
this against the job first):

- **No server-side environment.** `awesomate_app_set_env` returns 400 for a
  static app. Anything the page must keep secret has nowhere to live — it
  would be in the page source, readable by anyone.
- **`awesomate_n8n_attach_to_app` is Node-only.** A static lead form can only
  POST to an n8n webhook URL that is **hardcoded in the page and therefore
  public**. Sometimes that's acceptable (a plain lead capture behind n8n-side
  validation); when it isn't, it's a Node app.
- **No separate dev site.** All three environment URLs are the same single
  subdomain, so there's nowhere to review a change before it's live.
- **No deploy workflow.** The static template is just the page files —
  pushing to GitHub does not publish it (awesomate-github §2).
| A tool/app with **logins, custom logic, a dashboard, or an API** | **Node app** (`kind: 'node'`) | A real backend + database. |

### Within a Node app: which starter template?
Pick by the job (full catalog with descriptions: `awesomate_app_context.templates`):

| Job | `template` | Ships with |
|---|---|---|
| People **sign in** / per-user data | `node-auth-sync` | signup/login (JWT + bcrypt), MySQL migrations |
| Stores **structured data, no logins** — trackers, dashboards, internal tools | `node-crud-postgres` | ready-made records CRUD API + tiny UI, Postgres migrations (transactional) |
| **Webhooks / integrations / glue** — receives or serves JSON, little state | `node-api-only` | versioned `/api/v1` routes, CORS, optional `x-api-key` gate, no DB wiring |

All three include `src/lib/n8n.ts` and the same push-to-deploy workflow.

### Within a Node app: which database?
- **postgres** — relational data with relationships, concurrency, JSON columns,
  or analytics/AI features. The modern default for a real app.
- **mysql** — simple/legacy needs, or when they already know MySQL.
- Omit `dbEngine` and `awesomate_app_create` uses the template's native engine
  (`node-crud-postgres` → postgres). The app's `.env` gets `DB_ENGINE`,
  `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`, and a ready-to-use
  `DATABASE_URL` — even `node-api-only` gets one, sitting idle until wired.

## Questions that resolve the choice fast
1. "Is this mainly a **page people read** (marketing, blog, shop) or a **tool
   people use** (log in, do things, see their own data)?" → read → WP/static;
   tool → Node.
2. If read: "Do you need to **publish/edit content often** (blog, many pages)?"
   → yes → WordPress; no → static.
3. If tool: "Will people **sign in** or does it store data per user?" → yes →
   Node + postgres.

## Does it need a backend job? Prefer their n8n.
If the ask includes **email someone, look something up in their apps, save a
lead somewhere, or use AI**, that's usually a job for their **own n8n** — their
credentials are already connected there, so there's nothing new to set up.

- Check what's connected with `awesomate_n8n_inspect {what:'credentials'}`
  (names/types only) and offer what they already have: *"You've got Gmail +
  Google Sheets connected — want the form to email you and add the lead to a
  sheet?"* That read needs the **"Build and change automations from Claude Code"**
  privacy toggle, which is off by default — a 403 `consent_required` means
  call `awesomate_privacy_settings`, name the toggle, and ask the user to flip
  it at hub.awesomate.ai/settings?tab=privacy.
- Build the workflow with the **awesomate-n8n** skill (webhook trigger →
  action), take its **webhook URL**, and wire it into the app.
  - **Node app:** `awesomate_n8n_attach_to_app` — it stores
    `N8N_WEBHOOK_URL` plus a generated `N8N_WEBHOOK_SECRET` (encrypted +
    injected) and returns the secret so you can add the matching
    `X-Awesomate-Webhook-Secret` check on the n8n side. `src/lib/n8n.ts`
    POSTs there.
  - **Static site:** there is no app environment, so the URL sits in the page
    source, public. Tell the user that plainly, and defend the workflow on the
    n8n side instead (validation, rate limiting) — or use a Node app.
- Skip n8n for pure in-app logic with no external app/credential/AI — a webhook
  round-trip just adds latency and a failure point.

## Always, for any public site
Offer **awesomate-seo** (meta/OG tags, `sitemap.xml`, `robots.txt`, JSON-LD, a
general `llms.txt`) so it's findable by search engines *and* AI assistants — and
**awesomate-github** so their work is version-controlled from day one.
Push-to-deploy is a second step and not one you can finish alone: the Actions
workflow needs SSH repo secrets no client-side tool returns, so set up the repo
and hand the deploy wiring to Awesomate support (awesomate-github §2).