@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 sign-up box or a free
  download on a static page needs no secret: it is the hub's own form
  (`awesomate_crm_forms`, the awesomate-funnels skill), pasted into the page,
  which works only on that site. A form that must POST to an n8n webhook can
  only use a URL **hardcoded in the page and therefore public**. Sometimes
  that's acceptable (a plain enquiry 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 **"Let Claude Code work with your automations"**
  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, written through the user's own n8n MCP server), take its
  **production webhook URL**, and wire it into the app.
  - **Node app:** `awesomate_n8n_attach_to_app` with that URL. 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).