AI project docuimentation

DECISIONS.md

@@ -19,18 +19,40 @@ This document outlines the decisions made during the development of the Ledgerrz
 
 ## Architectural & Integration Decisions
 
-### 1. Style Architecture Shift to BEM
-To improve front-end maintainability, we transitioned the core reusable layout and page components away from raw utility-class markup. Styles are now strictly encapsulated within Vue Single File Component (SFC) `<style scoped>` blocks. To keep the look and feel 100% intact, we used Tailwind v4 `@apply` directives inside these blocks, referencing our central stylesheet (`@reference "../../css/app.css"`) to pull in custom themes and variables cleanly.
-*Note:* Third-party shadcn-vue library primitives (located in `components/ui/`) were kept intact to preserve vendor update integrity.
+### 1. Style Architecture Shift to BEM & Modern CSS Nesting
+To improve front-end maintainability, we transitioned the core reusable layout and page components away from raw utility-class markup. Styles are now strictly encapsulated within Vue Single File Component (SFC) `<style scoped>` blocks (or dedicated BEM component files under `/resources/css/components/`).
+*   **CSS Nesting Standard (Critical Learning):** Standard CSS/PostCSS nesting (unlike SASS) **does not** support class suffix concatenation (e.g. `.block { &__element { ... } }` is invalid). All nested selectors must declare the full class name explicitly (e.g. `.block { .block__element { ... } }`), compiling to standard descendant selectors (`.block .block__element`). Suffix nesting was refactored across all 12 component stylesheets to ensure native CSS browser and LightningCSS compatibility.
+*   **Encapsulation:** Used Tailwind v4 `@apply` directives inside these blocks, referencing our central stylesheet (`@reference "../../css/app.css"`) to pull in custom themes and variables cleanly.
+*   **Third-Party Safety:** Third-party shadcn-vue library primitives (located in `components/ui/`) were kept intact to preserve vendor update integrity.
 
-### 2. Robust Real-time Echo Fallback & Deduplication
+### 2. BelongsToMany Pivot Loading caveat
+When accessing pivot attributes on relationship models on the front-end (e.g. `participant.pivot.role`), the relationship definition in the Eloquent model **must** explicitly call `->withPivot('role')`. Omitting this will cause the pivot object to fail loading role attributes silently in Javascript, breaking role-based template gates. We added this to `App\Models\Dynamic::participants()`.
+
+### 3. Robust Real-time Echo Fallback & Deduplication
 To address potential initialization and bundling errors under local-development:
 *   **Module Deduplication:** Configured `resolve.dedupe: ['@laravel/echo-vue']` in `vite.config.ts` to ensure exactly one instance of the Echo plugin and configuration state is shared across main and lazy-loaded bundles.
 *   **Defensive Initialization:** Added checks using `echoIsConfigured()` and configured fallback connection parameters (e.g., `'mock-key'`) in both `app.ts` and `Chat.vue`'s setup functions. This ensures that missing environment variables (such as `VITE_REVERB_APP_KEY`) do not trigger fatal Pusher initialization crashes that block component rendering, allowing the websocket to fail silently (which is correct when Reverb is not running locally).
 
-### 3. Controller Authorization Fix
+### 4. Controller Authorization Fix
 We imported the `Illuminate\Foundation\Auth\Access\AuthorizesRequests` trait directly into `LedgerController.php`. This fixes the 500 Internal Server Error when loading the ledger page, which was caused by `LedgerController` calling `$this->authorize('view', ...)` without inheriting the required method from the Laravel 11 base `Controller`.
 
+### 5. Polymorphic Multiple-Media Attachment Support
+We added a polymorphic attachments system allowing any database model to attach multiple photos and videos cleanly:
+*   Created `Media` polymorphic model and a migration mapping `mediable_id` and `mediable_type`.
+*   Attached and verified uploads across `Message` (inline chat images/videos), `Ledger` (cover documents), and `Mutation` (chore submission receipts and proof).
+*   Built a highly reusable `.c-lightbox` CSS component for modal previews of both image and video uploads, avoiding duplication in individual modules.
+
+### 6. Cryptographically Secure Dynamic Invitation System
+We implemented a secure Dynamic Invitation flow to allow owners to invite new members to a Dynamic under a specific role:
+*   **Signed temporary URLs:** Invitation links dispatched in mailable emails (`DynamicInvitationMail.php`) use Laravel's temporary signed URLs, expiring in 7 days, to prevent link tampering.
+*   **Intended-Email Check Gate:** To prevent link hijacking, the accept gate strictly checks that the authenticated user's email matches the exact email specified on the invitation:
+    ```php
+    if ($request->user()->email !== $invitation->email) {
+        abort(403, 'This invitation was sent to a different email address.');
+    }
+    ```
+*   **Access Control:** Access to invitations and creation is fully protected under Owner-only authorization checks.
+
 ## Initial Database Schema
 
 I will start with a basic schema and evolve it as I build features.