# How an app fits together

A Foundation app is a set of parts that snap together. You turn on the ones you need; Foundation
connects them and runs them. This page is the mental model — once it clicks, the rest of the docs are
just detail.

## It's all configuration

Every app is defined by configuration, not code:

- **Which capabilities are on** — users, billing, data, AI, integrations
- **How each is set up** — your auth method, your plans, your data models
- **What's exposed** — REST API, MCP, API-as-a-service (a switch per capability)
- **Who can do what** — roles and scopes, across everything

You set that config however you like — the result is identical.

## The kernel, and the parts you add

Every app — even a tiny one — comes with a **kernel**:

- It deploys and runs (shared or dedicated infrastructure)
- It has an API surface (REST + MCP, off by default, flipped on per capability)
- It has a roles & scopes engine that governs access to everything
- It can have a custom domain and SSL

On top of the kernel you switch on **capabilities** as needed:

| Capability | What it adds |
|---|---|
| Identity | Login, registration, OAuth, API keys |
| Data | Entities (a database), file storage |
| Monetization | Stripe, plans, usage limits, gating |
| AI | Prompts and actions, wired to your data |
| Integrations | Connect outside services as tools |

## How the parts connect

The power is in how the parts reference each other — this is the glue Foundation handles so you don't
have to:

- **Plans gate capabilities.** A billing plan maps to usage limits, so "Pro unlocks AI" just works.
- **Entities power actions.** Your AI prompts and actions can read and write your data.
- **Integrations become tools.** A connected service's methods can be called by your actions, your
  API, or an AI agent.
- **Roles & scopes cut across all of it.** One permission model decides who — and which bots — can
  touch each entity, action, and integration.

You don't wire these together by hand. You turn things on; Foundation connects them.

## What you get when you deploy

Deploying provisions the real infrastructure behind those capabilities:

| You configured | You get |
|---|---|
| Users | Auth (Cognito or Auth0), user pools, OAuth |
| Data | A database for your entities, plus file storage |
| Billing | A live Stripe connection and plan management |
| API | REST endpoints and an MCP server |
| Domain | A custom domain with automatic SSL |

## Shared or dedicated

| | What it is | Best for |
|---|---|---|
| **Shared** | Runs on Foundation's shared infrastructure | Getting started — fast and cheap |
| **Dedicated** | Your own isolated infrastructure, domain, and auth | Production and businesses |

These are points on a spectrum, not rival choices — start shared and move to dedicated when you're
ready.

## Apps can have apps

A Foundation app can spawn **child apps** that share the parent's resources — the basis for
marketplaces, plugin ecosystems, and multi-tenant platforms. More on this when you need it.

Next: [Three ways to build & manage](/understand/three-ways-to-build).