ledgerrz/DECISIONS.md

Decisions

This document outlines the decisions made during the development of the Ledgerrz application.

Core Concepts

• Dynamic: A relationship between two or more users. This will be the core container for interactions.
• Ledger: A score-tracking entity within a Dynamic. The name "Ledger" will be used instead of "Score" to establish a more distinct domain language.
• Mutation: An event that modifies a Ledger. It can be a direct modification or a suggestion requiring approval.
• Participant: A user's role within a Dynamic. This will be used to manage permissions.

Technology Stack

• Backend: Laravel
• Frontend: Vue.js with Inertia.js
• Real-time: Laravel Echo via @laravel/echo-vue for notifications and real-time updates.
• Testing: Pest for PHP tests.
• Styling: BEM (Block, Element, Modifier) methodology. Replaced verbose inline Tailwind classes in custom HTML templates with semantic BEM classes (e.g., .c-chat, .user-info__avatar), and mapped them to CSS rules using Tailwind v4's @apply directive inside scoped <style> blocks. This preserves the clean, dark, BDSM-themed aesthetic while significantly improving markup readability.

Architectural & Integration Decisions

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. 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).

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:

  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.

7. Centralized Activity Service for System Messages

We created app/Services/ActivityService.php to centralize the creation of system messages and activities.

• System Messages as null user_id: System messages are stored as Message records with a null user_id, cleanly distinguishing them from user-generated content.
• Polymorphic Subject Linking: System messages are linked to relevant entities (e.g., a User who joined a dynamic, a Ledger that was created) via a polymorphic subject relationship on the messages table. This allows system messages on the dashboard to link directly to the relevant entity.
• Seeder Refactoring: The DatabaseSeeder was refactored to use the ActivityService to generate all system messages, ensuring consistency.

8. Event-Driven Automated System Logging

We relocated the dynamic system activity message generation out of individual controller endpoints and into the Eloquent Mutation Model's booted -> created event hook.

• Unified generation: Any mutation creation (whether occurring via a controller submission, an automated Pest test factory, or seeders during php artisan db:seed) now automatically and reliably generates correct system log messages.
• Database Seeder fixed: Reverted the database seeder (DatabaseSeeder.php) back to using standard clean Eloquent creations. Since model events automatically trigger, php artisan db:seed executes cleanly and builds a rich, fully populated database history with system messages out-of-the-box.

9. Standardized Policy-Driven UI Capabilities (can prop)

To maintain strict data security and clean up front-end markup, we eliminated unstandardized, hardcoded client-side role checks (like isOwner properties or manual pivot.role === 'owner' checks) and replaced them completely with dynamic policy-driven capabilities returned directly from Laravel policies as can objects.

• Centralized checks: Both the dynamic and ledger show routes return a standard can prop to the frontend (e.g., can: { update: boolean, close: boolean }).
• Polymorphic Resource Capabilities: Each mutation model is wrapped in MutationResource which appends its own localized policy checks (update for approving suggestions, void for voiding) at the individual record level.
• State-based policies: The MutationPolicy methods enforce both ownership authorization and state-based business constraints simultaneously (e.g., a mutation can be approved/updated only if its status is currently 'pending'; and can be voided only if its status is not 'voided'). This keeps the Vue templates purely declarative (e.g., v-if="mutation.can.update") and automatically protects the backend controllers against illegal state transitions.

10. Ledger-Scoped Predefined Mutation Templates ("Rewards")

Predefined mutations act as point-based templates ("purchases" or reusable chores) and belong strictly to specific Ledgers instead of broad Dynamics.

• Domain Alignment: Moving the resource nesting under ledgers (dynamics.ledgers.predefined-mutations) aligns perfectly with the mental model of spending points on a ledger.
• Type-Less Rewards: To simplify both the database schema and UI/UX, we eliminated the explicit type column ('reward' vs. 'penalty') from predefined mutations. They act as generic point-carrying "Rewards" whose amount can naturellement be positive (earning points) or negative (making a purchase / deducting points) without requiring restrictive explicit categorization.

11. Silent XHR Chat Pagination & Smooth Scrolling UX

To optimize chat-feed performance and improve overall user experience:

• Silent pagination (No URL pollution): Rather than using Inertia router.get visits which push ?page=x into the browser URL and break history during page reloads, we implemented a silent background fetch (using native browser fetch()) that queries our dedicated messages JSON API endpoints and prepends older messages silently to the feed.
• Scroll Preservation: Added preserveScroll: true to the Inertia form.post call in Chat.vue to prevent the active page scroll position from jumping or shifting when a new message is successfully submitted.

Initial Database Schema

I will start with a basic schema and evolve it as I build features.

• users: Standard Laravel users table.
• dynamics:
  • id
  • name
  • rules (TEXT)
  • created_at, updated_at
• ledgers:
  • id
  • dynamic_id
  • name
  • rules (TEXT)
  • score (INTEGER, default 0)
  • created_at, updated_at
• mutations:
  • id
  • ledger_id
  • user_id (author)
  • type (e.g., 'addition', 'subtraction')
  • amount (INTEGER)
  • description (TEXT)
  • status (e.g., 'approved', 'pending', 'rejected')
  • created_at, updated_at
• participants: (Pivot table for users and dynamics)
  • user_id
  • dynamic_id
  • role (e.g., 'owner', 'editor', 'viewer')
• media: For handling media uploads associated with mutations.
• chats: For the chat streams on Dynamics and Mutations.

Development Approach

1. Setup: Set up basic project structure, including models and migrations for the initial schema.
2. Dynamics: Implement the creation and management of Dynamics.
3. Ledgers: Implement the creation and management of Ledgers within a Dynamic.
4. Mutations: Implement the core functionality of adding and suggesting mutations.
5. UI: Build out the Vue components for each feature, focusing on a clean, dark, BDSM-themed aesthetic.
6. Real-time: Integrate Laravel Reverb for notifications.
7. Testing: Write Pest tests for all new backend functionality.
8. Git: Use feature branches and make regular commits.

This is a living document and will be updated as the project progresses.