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

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.

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

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.

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.