Duarte
124 lines
3.9 KiB
Plaintext
124 lines
3.9 KiB
Plaintext
# .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
|