Ulas
51 lines
2.2 KiB
Plaintext
51 lines
2.2 KiB
Plaintext
# 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` |
|