# Project Development Rules

This document outlines the strict guidelines and standards for pair-programming and code development across sessions.

---

## 1. Documentation Synchronization Rule (CRITICAL)
Whenever any feature, file layout, database model, API endpoint, component, or system logic is created, modified, or deleted:
* You **MUST** update the relevant sections of `architecture.md`, `memory.md`, and `phases.md` in the same developer turn/commit.
* Documentation must match the codebase exactly; there must be **zero** discrepancy, assumptions, or trailing documentation debt.

---

## 2. Coding & Technical Standards

### A. Environment Variable Safety
* Do **not** hardcode API endpoints, JWT secrets, S3 bucket names, or MinIO endpoints.
* Always read configurations from `.env` (backend uses `process.env.VAR`, frontend uses `import.meta.env.VITE_VAR`).

### B. Security & Iframe Embedding Policies
* Keep Express security configurations using `helmet` aligned.
* **Frameguard must remain disabled** (`frameguard: false`) to allow authorized parent components to embed secure previews.
* Content Security Policy (CSP) must contain `"frame-ancestors": ["'self'", "http://localhost:5173", "http://localhost:5000"]` to prevent browsers from blocking localized iframe previews.

### C. Client-Side Document Previews & Thumbnails
* **Client-Side Processing**: Previews and thumbnails must run client-side. Use `docx-preview` for `.docx`, SheetJS (`xlsx`) for spreadsheets (`.xlsx`, `.xls`, `.csv`), and `PDF.js` for `.pdf`.
* **Dark Mode Styling Safeguards**: Always force an explicit dark text color (`color: #0f172a`) inside bare spreadsheet HTML containers (such as `.excel-thumbnail-container` or `.excel-preview-container`) so that cell text is readable even if the application layout is in dark mode.
* **Dynamic Full-Bleed Scaling**: Card thumbnails for Word and spreadsheet components must scale dynamically using a `ResizeObserver` based on the parent card width:
  ```typescript
  scale = parentWidth / innerDocumentWidth
  ```
* **Legacy Format Fallbacks**: For formats where client-side rendering is impossible (such as legacy OLE binary `.doc` and `.ppt` formats), provide gorgeous, type-aware cover mockup views.

### D. File Cleanups upon Deletion
* Always delete physical S3 objects when their database references are deleted:
  * In the backend asset controllers/services, verify if the asset URL starts with `/uploads/`.
  * If so, invoke `DeleteObjectCommand` on the S3 `s3Client` to remove the binary object from the MinIO bucket, preventing orphaned storage bloat.