> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

> How a Zite workspace is laid out: the monorepo, generated .zite/ files, config files, and the import conventions.

A workspace is a `zitejs` monorepo — one repository holding every app and workflow, the generated types,
and a shared design system. Agents build inside it; this page is the map so you (and they) know where
everything lives.

## Layout

```text theme={null}
my-workspace/
├── zite.config.json        # project config: name + basePublicIdentifier (the database)
├── zite.schema.json        # the enriched database schema (SDK names, field types)
├── zite.permissions.json   # roles + row-level rules (see Permissions file)
├── .zite/                  # generated: db.ts (typed database client) — never edit
├── packages/
│   └── components/         # shared shadcn/ui design system → @project/components
└── apps/
    └── helpdesk/           # one directory per app
        ├── src/
        │   ├── App.tsx     # app entry (you write this)
        │   ├── api/        # backend workflows — one file per workflow
        │   ├── lib/        # raw integration SDK usage (Slack, Stripe, …)
        │   └── index.css   # theme (CSS variables)
        ├── .zite/          # generated: api.ts, user.ts, auth.ts, backend.ts — never edit
        ├── zite.config.json # app config: accessMode, integrations, userSync, …
        └── vite / tailwind / tsconfig / package.json
```

## Generated files

The `.zite/` directories — at the workspace root and inside each app — are **generated and must never be
edited**. `src/main.tsx` is generated too. They're refreshed by `zitejs generate` whenever the schema or
workflows change (the build tools run this for you):

| File                                     | Import as             | Contains                                                  |
| ---------------------------------------- | --------------------- | --------------------------------------------------------- |
| `.zite/db.ts` (root)                     | `zitejs/db`           | The typed database client (`zite.<Table>`, `zite.sql`, …) |
| `apps/*/​.zite/api.ts`                   | `zitejs/api`          | Typed callers for the app's workflows                     |
| `apps/*/​.zite/auth.ts`                  | `zitejs/auth`         | `useAuth`, narrowed to this app's `User` type             |
| `apps/*/​.zite/backend.ts`               | `zitejs/backend`      | `createEndpoint`, `ZiteError`, typed `context`            |
| `apps/*/​.zite/integrations/airtable.ts` | `zitejs/integrations` | Typed Airtable client (if Airtable is connected)          |

Read them to learn the exact table names, record types, and workflow signatures — never modify them.

## Import conventions

* **Platform SDKs** — always via `zitejs/*` aliases: `zitejs/db`, `zitejs/backend`, `zitejs/api`,
  `zitejs/auth`, and the utility modules (`zitejs/schedules`, `zitejs/notifications`, `zitejs/pdf`,
  `zitejs/upload`). Never import from `.zite/` by relative path.
* **Shared UI** — from `@project/components/ui/*` (e.g. `import { Button } from '@project/components/ui/button'`).
* **Your own files** — components, hooks, and utilities you create in an app's `src/` — via relative paths
  (`./components/Foo`).

## Config files

<CardGroup cols={2}>
  <Card title="zite.config.json (project)">
    At the workspace root: `{ "project": { "name": "...", "basePublicIdentifier": "..." } }` — the workspace
    name and the id of its database.
  </Card>

  <Card title="zite.config.json (app)">
    In each `apps/<dir>/`: `accessMode`, `integrations`, `userSync`, `envVars`, `authentication`,
    `seoSettings`, `pwaSettings`. See [Authentication](/concepts/authentication).
  </Card>

  <Card title="zite.schema.json">
    The enriched database schema — table and field SDK names, types, and options. Drives `.zite/db.ts`.
  </Card>

  <Card title="zite.permissions.json" href="/framework/permissions-file">
    Roles and the row-level rules that govern the workspace database.
  </Card>
</CardGroup>