From 6a923341257138d92abb477bdfeab0e03643787d Mon Sep 17 00:00:00 2001 From: Daan Meijer Date: Wed, 17 Jun 2026 01:17:27 +0200 Subject: [PATCH] docs: Document ActivityService and system message architecture in AGENTS.md and DECISIONS.md --- AGENTS.md | 6 ++++++ DECISIONS.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 02424cb..4a4a8ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,12 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac - Stick to existing directory structure; don't create new base folders without approval. - Do not change the application's dependencies without approval. +## Activity Service + +- The `app/Services/ActivityService.php` class is used to create system messages and activities. +- To create a system message, use the `createMessage` method. The `$user` parameter should be `null` to indicate a system message. +- The `createMutation` method can be used to create a mutation and its associated system message. + ## Frontend Bundling - If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. diff --git a/DECISIONS.md b/DECISIONS.md index b44827d..14984b1 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -53,6 +53,12 @@ We implemented a secure Dynamic Invitation flow to allow owners to invite new me ``` * **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. + ## Initial Database Schema I will start with a basic schema and evolve it as I build features.