Refactor: broadcasting + APP_PORT env added

Author: devvir

.docker/deploy

@@ -28,7 +28,7 @@ echo -e "${BLUE}📝 Setting up environment...${NC}"
 # 3. Start dev services (without assets container)
 echo -e "${BLUE}🐳 Starting containers...${NC}"
 export COMPOSE_PROJECT_NAME=dev
-"$SCRIPTS_DIR/compose.sh" up php nginx mysql mailhog --build -d
+"$SCRIPTS_DIR/compose.sh" up php nginx mysql mailhog reverb --build -d
 
 # 4. Wait for services to be healthy
 echo -e "${BLUE}⏳ Waiting for database...${NC}"

.docker/scripts/staging.sh

@@ -4,6 +4,7 @@ APP_KEY=
 APP_DEBUG=true
 APP_TIMEZONE=UTC
 APP_URL=http://localhost:8000
+APP_PORT=8000
 
 APP_LOCALE=es_UY
 APP_FALLBACK_LOCALE=en

.env.template

@@ -1,6 +1,6 @@
 # MTAV - Core Knowledge Base
 
-**Last Updated:** 2025-11-20
+**Last Updated:** 2025-01-27
 
 This document contains the essential architectural principles, patterns, and constraints needed for daily development work on MTAV.
 
@@ -58,7 +58,15 @@ This document contains the essential architectural principles, patterns, and con
 - **Admin/Member are mutually exclusive** - cannot be both
 - **Project-based scoping** - most models automatically scoped to current project context
 
-**Reference**: See `policies-reference.md` for detailed authorization patterns.
+**User Type Implementation**: Uses a **pseudo-STI pattern** (not true Single Table Inheritance):
+- `Admin` and `Member` classes extend `User` but use **global scopes** to filter queries
+- `Admin` scope: `where('is_admin', true)`
+- `Member` scope: `where('is_admin', false)->whereNotNull('family_id')`
+- No `type` discriminator column - type determined by `is_admin` boolean and `family_id` presence
+- `User` model creates helper instances (`adminCast`, `memberCast`) via `Admin::make()` and `Member::make()` for type-specific behavior
+- **Important**: Queries on `Admin::query()` or `Member::query()` are automatically filtered by global scopes
+
+**Reference**: See `policies-reference.md` for detailed authorization patterns and `core/USER_SYSTEM.md` for user type implementation details.
 
 ---
 
@@ -132,7 +140,11 @@ This document contains the essential architectural principles, patterns, and con
 
 ## Queue Workers (Background Jobs)
 
-**Development**: Uses `sync` driver - jobs execute immediately in the request (no background processing)
+**Development**: Queue driver is configurable via `QUEUE_CONNECTION` environment variable:
+- **Default in config**: `database` (set in `config/queue.php` line 16)
+- **Typical dev setup**: Override via `.env` to use `sync` or `deferred` for immediate/queued execution
+- **Tests**: Always use `sync` driver (set in `phpunit.xml` line 40) - jobs execute immediately in test requests
+- **No background workers in dev**: Development typically uses `sync` or `deferred` to avoid running queue workers
 
 **Production**: Uses `database` driver with supervisord-managed queue workers:
 - **3-5 queue worker processes** managed by supervisord
@@ -142,7 +154,7 @@ This document contains the essential architectural principles, patterns, and con
 - Container: `queue` service in production compose
 
 **Queue Configuration**:
-- Default connection: `database` (set in `config/queue.php`)
+- Default connection: `database` (set in `config/queue.php` line 16, can be overridden via `QUEUE_CONNECTION` env var)
 - Table: `jobs` (created during migrations)
 - Retry logic: 3 attempts, 90-second timeout between retries
 

documentation/ai/KNOWLEDGE_BASE.md

@@ -109,7 +109,7 @@ documentation/ai/
 - Test helpers go in `tests/Helpers/` (autoloaded by Pest)
 
 **Key architectural patterns** (internalize these):
-- **STI (Single Table Inheritance)**: User → Admin/Member (see `core/USER_SYSTEM.md`)
+- **Pseudo-STI (Scope-Based Type Discrimination)**: User → Admin/Member via global scopes, not true STI (see `core/USER_SYSTEM.md`)
 - **Family Atomicity**: Families are atomic units, members mirror family's project
 - **Two-Level Auth**: Global scopes (query) + Policies (action) (see `core/SCOPING.md`)
 - **Universe Fixture**: `universe.sql` loaded once, rolled back per test
@@ -187,7 +187,7 @@ documentation/ai/
 ### Core System Patterns
 
 **`core/USER_SYSTEM.md`** - Complete user type system
-- STI (Single Table Inheritance) pattern
+- Pseudo-STI (scope-based type discrimination) pattern
 - Member/Admin/Superadmin capabilities
 - Database schema, relationships
 - Validation rules, constraints

documentation/ai/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-MTAV uses **Single Table Inheritance (STI)** for user management with three distinct actor types:
+MTAV uses a **pseudo-STI pattern** (scope-based type discrimination) for user management with three distinct actor types:
 
 ```
 Superadmin (highest privileges)
@@ -12,6 +12,13 @@ Admin (project-scoped management)
 Member (family-bound participation)
 ```
 
+**Implementation Pattern**: This is **NOT true Single Table Inheritance** (no `type` discriminator column). Instead:
+- `Admin` and `Member` classes extend `User`
+- Type discrimination via **global scopes** on `is_admin` boolean and `family_id` presence
+- `Admin::query()` automatically scoped to `where('is_admin', true)`
+- `Member::query()` automatically scoped to `where('is_admin', false)->whereNotNull('family_id')`
+- `User` model creates helper instances (`adminCast`, `memberCast`) for type-specific behavior
+
 **Key Principle**: Admins and Members are **mutually exclusive** - a user cannot be both.
 
 ---
@@ -237,8 +244,9 @@ $user->isSuperadmin() // true if email in config array AND is_admin = true
 
 ### User (Base Model)
 
-**Pattern**: Single Table Inheritance (STI)
-**Discriminator**: `is_admin` field
+**Pattern**: Pseudo-STI (scope-based type discrimination)
+**Type Discriminator**: `is_admin` boolean field + `family_id` presence
+**Implementation**: Global scopes on `Admin` and `Member` subclasses filter queries automatically
 
 **Validation Rules**:
 - `firstname`: REQUIRED, string, max:255
@@ -262,13 +270,18 @@ public function activeProjects(): BelongsToMany
 
 **Model Methods**:
 ```php
-public function isSuperadmin(): bool
-public function isAdmin(): bool
-public function isMember(): bool
-public function toAdmin(): ?Admin
-public function toMember(): ?Member
+public function isSuperadmin(): bool  // Checks email in config + is_admin = true
+public function isAdmin(): bool      // Returns is_admin || isSuperadmin()
+public function isMember(): bool     // Returns !is_admin
+public function asAdmin(): ?Admin    // Returns adminCast helper instance
+public function asMember(): ?Member  // Returns memberCast helper instance
 ```
 
+**Type Casting Behavior**:
+- `User` model's `booted()` method creates `Admin` or `Member` instances via `Admin::make()` and `Member::make()`
+- These are stored as `adminCast` and `memberCast` properties for type-specific method access
+- **Important**: These are helper instances, not the actual model - queries still go through global scopes
+
 **Soft Delete Behavior**:
 - Uses `SoftDeletes` trait
 - Setting `deleted_at` marks user as deleted
@@ -278,20 +291,30 @@ public function toMember(): ?Member
 ### Admin Model
 
 **Extends**: User
-**Global Scope**: `where('is_admin', true)`
+**Global Scope**: `where('is_admin', true)` (applied automatically to all `Admin::query()` calls)
+**Table**: Uses `users` table (shared with all user types)
+**Key Behavior**: 
+- All queries on `Admin::query()` are automatically filtered to `is_admin = true`
+- Cannot query admins via `User::query()` without bypassing scope
+- Helper instance created in `User::booted()` as `adminCast` property
 
 **Additional Methods**:
-- Project management helpers
-- Admin-specific relationships
+- Project management helpers (`manages()`)
+- Admin-specific relationships (`events()`, `upcomingEvents()`)
 
 ### Member Model
 
 **Extends**: User
-**Global Scope**: `where('is_admin', false)`
+**Global Scope**: `where('is_admin', false)->whereNotNull('family_id')` (applied automatically to all `Member::query()` calls)
+**Table**: Uses `users` table (shared with all user types)
+**Key Behavior**:
+- All queries on `Member::query()` are automatically filtered to `is_admin = false AND family_id IS NOT NULL`
+- Cannot query members via `User::query()` without bypassing scope
+- Helper instance created in `User::booted()` as `memberCast` property
 
 **Additional Methods**:
-- Family-specific helpers
-- Member-specific relationships
+- Family-specific helpers (`family()`, `project()`)
+- Member-specific relationships (`rsvps()`, `events()`)
 
 ---
 

documentation/ai/core/USER_SYSTEM.md

@@ -10,24 +10,24 @@ import { useBroadcasting } from '@/composables/useBroadcasting';
 const { onMessage, onPrivateMessage, onProjectMessage, onAnyMessage } = useBroadcasting();
 
 // Listen for navigation messages
-onMessage('user.navigation', (message) => {
-  console.log('[AppSidebarHeader] Navigation message received:', message);
-});
+// onMessage('user.navigation', (message) => {
+//   console.log('[AppSidebarHeader] Navigation message received:', message);
+// });
 
 // Listen for any private channel message
-onPrivateMessage((message) => {
-  console.log('[AppSidebarHeader] Private channel message:', message);
-});
+// onPrivateMessage((message) => {
+//   console.log('[AppSidebarHeader] Private channel message:', message);
+// });
 
 // Listen for project messages
-onProjectMessage((message, projectId) => {
-  console.log('[AppSidebarHeader] Project message:', message, 'Project ID:', projectId);
-});
+// onProjectMessage((message, projectId) => {
+//   console.log('[AppSidebarHeader] Project message:', message, 'Project ID:', projectId);
+// });
 
 // Listen to everything
-onAnyMessage((message) => {
-  console.log('[AppSidebarHeader] ANY message received:', message);
-});
+// onAnyMessage((message) => {
+//   console.log('[AppSidebarHeader] ANY message received:', message);
+// });
 </script>
 
 <template>

resources/js/components/layout/header/AppSidebarHeader.vue

@@ -62,16 +62,16 @@ export function useBroadcasting() {
   const initializeChannels = () => {
     if (!auth.value.user) return;
 
-    console.log('[useBroadcasting] Initializing channels for user:', auth.value.user.id);
-    console.log('[useBroadcasting] Available projects:', auth.value.projects);
+    // console.log('[useBroadcasting] Initializing channels for user:', auth.value.user.id);
+    // console.log('[useBroadcasting] Available projects:', auth.value.projects);
 
     // Connect to private channel
     connectToPrivateChannel();
 
     // Connect to project channels
     if (projects.value.length) {
       projects.value.forEach((project: any) => {
-        console.log('[useBroadcasting] Connecting to project channel:', project.id);
+        // console.log('[useBroadcasting] Connecting to project channel:', project.id);
         connectToProjectChannel(project.id);
       });
     }
@@ -99,7 +99,7 @@ export function useBroadcasting() {
     // Listen to all known message types
     MESSAGE_TYPES.forEach((type) => {
       channel.listen(`.${type}`, (data: BroadcastMessage) => {
-        console.log('[useBroadcasting] Private channel event:', { type, data });
+        // console.log('[useBroadcasting] Private channel event:', { type, data });
         triggerPrivateCallbacks(data);
         triggerMessageCallbacks(data);
         triggerAnyCallbacks(data);
@@ -119,20 +119,20 @@ export function useBroadcasting() {
     const channelName = `projects.${projectId}`;
     const key = `presence-${channelName}`;
 
-    console.log('[useBroadcasting] Attempting to join presence channel:', channelName);
+    // console.log('[useBroadcasting] Attempting to join presence channel:', channelName);
 
     if (subscriptions.has(key)) return; // Already subscribed
 
     const channel = echo().join(channelName) as PresenceChannel;
 
-    console.log('[useBroadcasting] Joined presence channel:', channelName);
+    // console.log('[useBroadcasting] Joined presence channel:', channelName);
 
     // Initialize online users list for this project
     onlineUsersByProject.set(projectId, []);
 
     // Handle initial presence
     channel.here((users: any[]) => {
-      console.log('[useBroadcasting] Users already in project channel:', users);
+      // console.log('[useBroadcasting] Users already in project channel:', users);
       const onlineUsers = users.map((user) => ({
         id: user.id,
         name: user.name,
@@ -143,7 +143,7 @@ export function useBroadcasting() {
 
     // Handle user joining
     channel.joining((user: any) => {
-      console.log('[useBroadcasting] User joining project channel:', user);
+      // console.log('[useBroadcasting] User joining project channel:', user);
       const users = onlineUsersByProject.get(projectId) || [];
       const newUser: OnlineUser = {
         id: user.id,
@@ -155,7 +155,7 @@ export function useBroadcasting() {
 
     // Handle user leaving
     channel.leaving((user: any) => {
-      console.log('[useBroadcasting] User leaving project channel:', user);
+      // console.log('[useBroadcasting] User leaving project channel:', user);
       const users = onlineUsersByProject.get(projectId) || [];
       onlineUsersByProject.set(
         projectId,
@@ -166,7 +166,7 @@ export function useBroadcasting() {
     // Listen to all known message types
     MESSAGE_TYPES.forEach((type) => {
       channel.listen(`.${type}`, (data: BroadcastMessage) => {
-        console.log('[useBroadcasting] Project channel event:', { type, data, projectId });
+        // console.log('[useBroadcasting] Project channel event:', { type, data, projectId });
         triggerProjectCallbacks(data, projectId);
         triggerMessageCallbacks(data);
         triggerAnyCallbacks(data);
@@ -194,7 +194,7 @@ export function useBroadcasting() {
     // Listen to all known message types
     MESSAGE_TYPES.forEach((type) => {
       channel.listen(`.${type}`, (data: BroadcastMessage) => {
-        console.log('[useBroadcasting] Global channel event:', { type, data });
+        // console.log('[useBroadcasting] Global channel event:', { type, data });
         triggerGlobalCallbacks(data);
         triggerMessageCallbacks(data);
         triggerAnyCallbacks(data);