# Oikos

Self-hosted family planner PWA. Node.js/Express, Vanilla JS (no build step), SQLite, Docker.

## Hard Constraints

Violations are always bugs - no exceptions.

- Never add frontend frameworks (React, Vue, Svelte), bundlers (Webpack, Vite), or CSS libraries (Tailwind, Bootstrap).
- No external frontend dependencies. Only allowed exception: Lucide Icons (`public/lucide.min.js`, self-hosted). No CDN links at runtime.
- `import`/`export` everywhere. Never `require()`.
- Never `eval()`. Never `innerHTML` with user data. Use `textContent` or DOM API.
- All UI text via `t('key')`. Never hardcode strings in components. `de` is the reference locale.
- Migrations append-only. Add entries to the `migrations` array in `server/db.js`. Never modify or reorder existing entries.
- All colors, radii, shadows, font sizes from `public/styles/tokens.css`. Never hardcode design values.
- Every route handler in `try/catch`. No unhandled promise rejections.

## Architecture

Request flow: client → Express static (`public/`) or `/api/v1/*` → session auth → route handler → better-sqlite3 (sync) → JSON.

Key locations that are non-obvious:
- `public/i18n.js` - `t()`, `formatDate()`, `formatTime()`, `SUPPORTED_LOCALES`
- `public/api.js` - fetch wrapper (handles auth, CSRF, errors)
- `public/router.js` - History API router (no library)

## Conventions

- API responses: `{ data: ... }` on success, `{ error: string, code: number }` on failure.
- Dates/times: always `formatDate()`/`formatTime()` from `i18n.js`. Never format manually.
- Pages (`public/pages/*.js`): export `render()`. No side effects on import.
- Web Components (`public/components/*.js`): `oikos-` prefix, one component per file.
- Tests: `test-[module].js` in project root, `--experimental-sqlite` flag. Add `test:[module]` script to `package.json`.

## Verification

```bash
npm run dev    # Start with --watch
npm test       # All test suites (requires Node ≥22)
```

## Reference

| What | Where |
|------|-------|
| Data model, UI specs | `docs/SPEC.md` |
| Design tokens | `public/styles/tokens.css` |
| DB schema (source of truth) | `server/db.js` |
| i18n keys | `public/locales/de.json` |
| Code conventions, commit format | `CONTRIBUTING.md` |