# .clinrules

## Project Overview

This project is a personal web application developed using a unified, full-stack architecture:

* SvelteKit (latest stable, Node adapter)
* TypeScript
* Bootstrap 5
* SQLite (local file-based database)
* Drizzle ORM (lightweight, type-safe SQL query builder)
* Caddy or Nginx (production reverse proxy with SSL)

Primary goals:

1. Simplicity
2. Minimal operational overhead (suited for a small VPS with 2 cores, 4GB RAM)
3. High readability and maintainability
4. Fast development cycle
5. AI-generated code consistency

The application is targeted specifically for desktop browsers and tablet devices, and is expected to remain relatively small (<20 database tables) with low concurrency (<5 users).

---

## General Principles

* Prefer the simplest solution that satisfies the requirement.
* Avoid over-engineering and premature optimization.
* Avoid introducing unnecessary abstractions (e.g., repository patterns).
* Favor explicit code over clever/implicit code.
* Prioritize readability over conciseness.

---

## Architecture (SvelteKit Full-Stack)

We use SvelteKit's unified server/client model. There is no separate backend service.

```text
src/
├── routes/             # SvelteKit pages and server endpoints (+page.svelte, +page.server.ts, +server.ts)
├── lib/
│   ├── components/     # Reusable Svelte UI components
│   ├── db/             # Database connection, schemas, and migrations
│   │   ├── schema.ts   # Drizzle schema definitions
│   │   └── index.ts    # SQLite client initialization
│   ├── services/       # Server-side business logic
│   ├── types/          # Shared TypeScript definitions
│   └── utils/          # Helper functions
```

Rules:
* Use TypeScript everywhere.
* Keep components focused and small.
* Implement business logic in `lib/services/` or directly inside `+page.server.ts` actions.
* Never query the database directly from frontend code; database queries must occur exclusively in server files (`*.server.ts`).

---

## Database (SQLite + Drizzle)

Use:
* SQLite (local file: e.g., `data/sqlite.db`)
* Drizzle ORM for schema definitions and migrations

Rules:
* Define schemas explicitly in `src/lib/db/schema.ts`.
* Use Drizzle Kit for generating and running schema migrations.
* Use UUIDs or auto-incrementing integers for primary keys consistently.
* Define appropriate foreign keys and cascading delete rules.

---

## Authentication

Use:
* Secure cookie-based sessions (stored in the SQLite database).
* Password hashing using `argon2` or `bcrypt`.
* Manage sessions via SvelteKit server hooks (`src/hooks.server.ts`).
* Avoid external OAuth/identity providers unless explicitly requested.

---

## Bootstrap Rules

Use Bootstrap 5 as the primary UI framework.

Rules:
* Prefer standard Bootstrap components before creating custom CSS.
* Avoid unnecessary custom CSS; keep styling simple.
* Favor responsiveness using Bootstrap's responsive grid system and utility classes, with a primary design focus on desktop and tablet screens.

---

## Error Handling

* Handle errors explicitly on the server side.
* Return user-friendly error messages using SvelteKit's `error` helpers.
* Log technical details server-side. Never expose raw stack traces to the user interface.

---

## Deployment & Ops

* SvelteKit must be built using the Node adapter (`@sveltejs/adapter-node`) for server-side execution.
* The application runs locally or in production as a Node.js process listening on a port (e.g., `3000`).
* Nginx or Caddy handles SSL termination and reverse proxies requests to port `3000`.

---

## AI Agent Behavior

Before coding:
1. Understand the requirement.
2. Review existing files and follow established patterns.
3. Minimize changes.

Prohibitions (do NOT use unless explicitly requested):
* Clean Architecture / CQRS
* Event Sourcing
* Generic Repository Patterns
* Enterprise/Factory-heavy designs