# Core concepts

Interfold has a small, consistent model. Once these ideas click, the CLI and
API read like plain English.

## Accounts

An **account** is the workspace and billing boundary. Every site, file, function,
cron job, and secret belongs to exactly one account. Users join accounts through
membership; API keys are scoped to a single account with Read-only or Read/write
access. Read/write includes all reads. See [API authentication](/api-reference).

```sh
interfold accounts list
interfold accounts current
```

## Buckets

A **bucket** is an account-owned collection of files. It works without hosting:
store documents, source, assets, and data through the bucket Files API. A Site
can attach to a bucket; creating a Site without a bucket creates one automatically.

## Sites

A **site** attaches hosting and runtime behavior to one bucket, served at its own subdomain,
`https://<subdomain>.interfold.site`. A Site interprets fixed bucket directories and owns its runtime resources:

| Resource   | Path convention | Purpose                                         |
| ---------- | --------------- | ----------------------------------------------- |
| Web files  | `/web/*`        | Verbatim HTML, CSS, JS, images, and text        |
| Functions  | `/api/*.ts`     | Server-side TypeScript endpoints                |
| Cron Jobs  | `/cron/*.ts`    | Scheduled TypeScript handlers                   |
| Data files | `/data/*`       | File storage for functions and cron jobs        |
| Database   | —               | Structured SQL data for functions and cron jobs |

A site has an `access` setting (`PUBLIC` or `PRIVATE`) that controls who can
reach its static output. See [Sites & access](/sites).

## Files

Everything you publish is a **file** at a path. `interfold files put` creates or
replaces a file; the path determines how it behaves:

- `/web/index.html`, `/web/style.css`, `/web/logo.png` — **web files**, served at `/`, `/style.css`, and `/logo.png`.
- `/api/hello.ts` — a **function source**, deployed as an endpoint.
- `/cron/refresh.ts` — a **cron source**, deployed as a scheduled handler.
- `/data/state.json` — **data**, written by handlers, never served publicly.

The path is the source of truth. Files under `/web/` are served verbatim with
the prefix omitted from hosted URLs. There is no runtime Markdown rendering or
other transformation, and uploading is publishing. Because the prefix is
omitted, `/web/api/`, `/web/cron/`, `/web/data/`, and `/web/_interfold/` are
rejected rather than colliding with reserved hosted routes.

## Access

Bucket API access always requires account authentication. A Site's `PUBLIC` or
`PRIVATE` setting controls anonymous access only to hosted `/web/` files. A
deployed `/api/<name>` runtime is anonymously callable for either Site setting;
the handler must enforce any function-specific authorization. There are no
per-file overrides. Source, cron, data, database and migration assets, and
files outside `/web/` are never served directly; a function can still return
data deliberately.

See [Sites & access](/sites).

## Functions

A **function** is a single TypeScript file at `/api/<name>.ts` that exports a
`handler`. It runs on request and returns a standard `Response`. Functions get a
`ctx` object with access to persistent data and site secrets.

```ts
export async function handler(req: Request, ctx: InterfoldContext) {
  return Response.json({ ok: true, siteId: ctx.siteId })
}
```

See [Functions](/functions).

## Cron Jobs

A **cron job** is a TypeScript file at `/cron/<name>.ts` with a static UTC
schedule and a named `handler`. It runs in the same isolated environment as a
function, with access to site data and secrets but no browser request or user
session.

See [Cron Jobs](/cron-jobs).

## Storage & secrets

- **Databases** (`ctx.db`) store structured application data and support SQL
  queries and concurrent updates. See [Databases](/databases).
- **Data files** (`ctx.data`) store text, JSON, and JSONL under `/data/`. See
  [Data files](/data-storage).
- **Secrets** are named values set out-of-band and read at runtime via
  `ctx.secrets.get(...)`. Secret values never appear in source or logs. See
  [Secrets](/secrets).

---

Ready to build? Start with [Getting started](/getting-started), or browse the
[CLI](/cli) and [API](/api-reference) references.