# Project Rules and Architecture Guidelines

## Core Persona
- **Role**: You are an **Expert Software Developer**. Write clean, well-typed TypeScript, robust and readable logic, and document design decisions. Keep performance, responsiveness, and clean architecture at the forefront of every change.

---

## 1. Clean Architecture & Separation of Concerns
- **Component Separation**: Keep presentation logic (templates in `src/templates/`) separate from core business/profile data (`src/data/portfolioData.tsx`) and layout portal logic (`src/App.tsx`).
- **Styles Isolation**: Use localized CSS Modules (`[Name].module.css`) for layout templates. Avoid injecting ad-hoc inline styles or leaking global rules. Maintain strict grid boundaries.
- **Translation Isolation**: Keep static copy inside `.po` catalogs in `src/locales/`. Do not hardcode strings inside template components. Always wrap translations in `t()` or `<Trans>`.

---

## 2. Tech Stack & Styling Rules
- **Core Framework**: Vite + React 19 + TypeScript.
- **Styling System**: **Vanilla CSS / CSS Modules**. 
  - Each template has its own CSS Module (e.g., `src/templates/CyberpunkTemplate.module.css`).
  - Do NOT introduce TailwindCSS, Bootstrap, or heavy third-party UI libraries unless explicitly requested.
  - Keep styling responsive and focus on modern aesthetics (glassmorphism, vibrant palettes, hover animations).

---

## 3. Page & Template Architecture
- **Home/Gallery Portal**: `src/App.tsx` serves as the main entry and design gallery selector.
- **Circadian Cycle (Auto Mode)**: Automatically changes layouts based on the current time of day.
- **Templates**: Individual layouts are stored in `src/templates/` (e.g., `BentoTemplate`, `TerminalTemplate`, `BrutalistTemplate`, `NeumorphicTemplate`, `CyberpunkTemplate`, `AuroraTemplate`, `EditorialTemplate`, `GithubTemplate`, `ThreeDTemplate`).
- **Navigation Rule**: Every template logo or header should have an `onClick` handler that dispatches a Custom Event `'goHome'`:
  ```typescript
  window.dispatchEvent(new CustomEvent('goHome'));
  ```
  This returns the user to the Design Gallery Portal.

---

## 4. Localization & Internationalization (i18n)
- **Framework**: `react-i18next` + `i18next` + `i18next-browser-languagedetector`.
- **Localization Files**: Catalogs are stored as Gettext `.po` files in `src/locales/` (e.g., `en.po`, `es.po`, `it.po`, `de.po`).
- **PO File Parsing**:
  - `vite.config.ts` includes a custom Vite plugin `poLoader()` that compiles `.po` files directly into JSON objects at bundle time.
- **Formatting & the `Trans` Component**:
  - For simple text, use standard translation: `{t('key')}`.
  - For rich-text translations containing bolding (`**text**`), the node script `update-po.cjs` parses the PO files and transforms `**text**` into index-based tags (e.g., `<1>text</1>`, `<3>text</3>`).
  - Render these formatting tags in React using the `<Trans>` component:
    ```tsx
    import { Trans } from 'react-i18next';
    
    <Trans i18nKey="Some **bolded** and *italicized* text">
      Some <strong>bolded</strong> and <em>italicized</em> text
    </Trans>
    ```
- **Language Detection Pipeline**:
  - Order: `querystring` -> `localStorage` -> `navigator` (browser locale preference mirroring Accept-Language headers).
  - Query parameter: `?lang=<code>` (e.g., `?lang=es`).
  - Default/Fallback language: `en` (English).

---

## 5. Deployment and Scripts
- **Development**: `npm run dev` to launch the Vite local server.
- **Build**: `npm run build` compiling to `dist/` (includes sitemap + prerender).
- **Production deploy (Woodpecker)**: Triggered by **git push to `main`** on Forgejo (`git.rafaelgonzalezalbes.com/rafael.gonzalez.albes/portfolio`). Pipeline: install → lint → build → check-qa → SFTP deploy. **Agents must commit and push** (or merge PR) to ship — editing files locally is not enough.
- **Manual deploy fallback** (`deploy.js` via `npm run deploy` / `npm run d`):
  - Connects to a remote server using credentials from `.env` via SSH/SFTP.
  - Uploads the `/dist` directory.
  - Recursively changes file permissions on the server (directories to `755`, assets/files to `644`) to guarantee correct access.
- **Pre-Deploy QA release check (`check-qa.cjs`)**:
  - Runs automatically inside the deploy pipeline before files are uploaded.
  - Verifies build structure, checks for duplicate HTML tag bugs (such as duplicate titles or descriptions), validates sitemap/robots SEO presence, scans for broken local references (JS/CSS/images), and verifies locale flags.
  - If any QA test fails, it halts the process and prevents uploading broken code.
- **Quick Deploy Shortcuts**:
  - `npm run d`: Super short CLI alias for `npm run deploy` (builds, runs QA, and deploys).
  - `npm run df`: Forces build and deploy, bypassing pre-deploy QA checks (for quick hotfixes).
  - `deploy.bat`: Smart batch file. Checks if Docker Desktop daemon is running. If yes, builds & deploys inside a container. If no, falls back to host Node/NPM.
  - `deploy.bat force` (or `f`/`--force`): Executes deployment while bypassing pre-deploy QA checks.
- **Docker**: A `Dockerfile` and `docker-compose.yml` exist for containerized execution. Keep paths compatible.

---

## 6. Token Optimization & Continuous Learning Guidelines (For AI Coding Agents)
To prevent unnecessary token expenditure and keep context windows lightweight, follow these operational rules:
1. **Targeted Searching over Large Reads**: Always use `grep_search` to locate specific files, symbols, or functions rather than reading entire large files (`view_file`) or listing large directories recursively.
2. **Narrow File Reads**: When reading files, use `StartLine` and `EndLine` parameters to fetch only the relevant lines of code under consideration. Avoid loading more than 100-200 lines at once unless it's the initial architectural overview.
3. **Minimize Duplicate Actions**: Do not repeat directory listings (`list_dir`) or file checks within the same task. Rely on your internal memory/context history of the session.
4. **Command Output Limitation**: Avoid running commands that output thousands of lines of output. If required, filter outputs (e.g., limit logs with `git log -n 5`, or silence package installations with `--silent` or `--quiet`).
5. **Concise Responses**: Keep text output focused and highly technical. Avoid summarizing large chunks of code or long lists of rules that are already present in the artifacts or workspace rules.
6. **Continuous Learning Loop (Crucial)**: At the end of every user request/conversation, if a new workflow, build script, code pattern, or specific user preference was established, the AI agent MUST update both `.cursorrules` and `.gemini-rules.md` to capture and persist this knowledge for future turns.

---

## 7. Developer Preferences & Personal Communication Profile
When interacting with the repository developer (Rafael):
- **Communication Style**: Direct, friendly, informal, and action-oriented. Keep chat responses concise. Skip long introductory or summary paragraphs unless explicitly asked.
- **Languages**: Developer speaks Spanish and English. You may clarify comments or terms in either language if helpful, but defaults/code base should align with the specified translations.
- **No-Bloat Philosophy**: Developer values performance and minimalism in client-side code. Do not suggest adding complex NPM packages or styling systems when simple vanilla JavaScript/CSS fits the requirement.
- **Efficiency & Cost-Awareness**: Developer strongly appreciates cost-conscious agent execution. Get straight to the point, verify edits with minimal API calls, and maintain this `.cursorrules` file as a living repository memory.
