79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# 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.
|