# IAVICA
> Your AI builds the app. We keep the data.
IAVICA is a small persistence backend for HTML apps generated by AI. The app stays a single HTML file opened from disk (`file://`). IAVICA handles email identity, magic links, short sessions, multi-device access, sharing and versioned JSON storage.
## Start here
- Landing: https://iavica.com/
- AI instructions: https://iavica.com/ai/
- Quickstart: https://iavica.com/docs/quickstart/
- API reference: https://iavica.com/docs/api/
- Account panel: https://iavica.com/account/
- Machine-readable index: https://iavica.com/llms.txt
## Non-negotiable rules for AI assistants
1. Keep a stable `appId` (UUID v4) embedded in the HTML. Do not generate a new one on every load.
2. Never hardcode the user's email, tokens or secrets in the HTML.
3. Load the classic SDK: ``.
4. Call `Iavica.connect({ appId, appName, locale })` and `await db.ready()` before reading or writing.
5. Set `locale` to the app language (`en` or `es`), or pass custom `labels`.
6. Include a footer in the app language with a link to https://iavica.com and a logout control that calls `db.logout()`.
7. The footer must be localized, e.g. English: “Persistent data with IAVICA”, “Switch project”, “Log out”; Spanish: “Datos persistentes con IAVICA”, “Cambiar de proyecto”, “Cerrar sesión”.
8. Handle 401 (session), 409 (version conflict) and 429 (rate limit/quota) explicitly.
## Data model
- `appId`: public, stable app identifier. Not a password.
- Project: isolated data space. Each user gets their own project per app; sharing is explicit.
- Collection: logical group of JSON documents (e.g. `gastos`).
- Record: `{ id, data, version, createdAt, updatedAt }`.
- Member roles: `owner` or `editor`.
## Core endpoints
- `POST /v1/link-requests` — request a magic link: `{ appId, appName?, email }`.
- `GET /v1/link-requests/:id/status` — poll with `X-Iavica-Link-Secret`.
- `POST /v1/link-requests/:id/redeem` — exchange approval for session + device token.
- `GET|POST /v1/apps/:appId/collections/:collection/records`
- `PATCH|DELETE /v1/apps/:appId/collections/:collection/records/:id` — requires `If-Match: `.
- `POST /v1/apps/:appId/projects/:projectId/invitations` — owner invites an editor.
- `GET /v1/apps/:appId/projects/:projectId/export` — export project data.
- `POST /v1/sessions/refresh` and `POST /v1/sessions/disconnect`.
## Errors
`AUTH_REQUIRED` (401), `SESSION_EXPIRED` (401), `ACCESS_DENIED` (403), `LINK_EXPIRED` (410), `VERSION_CONFLICT` (409), `VALIDATION_ERROR` (400), `RATE_LIMITED` (429), `QUOTA_EXCEEDED` (429), `NOT_FOUND` (404).
Error shape: `{ error: { code, message, requestId, details? } }`.
## Security notes
- The `appId` is public; copying the HTML does not grant access.
- Magic links are single-use and short-lived; approval is an explicit POST.
- Sessions are short-lived; device tokens are revocable via logout.
- Optimistic concurrency prevents silent overwrites.
- The superadmin panel exposes audit events, blocks and telemetry; it is not part of the app SDK.