Skip to content

C
Clubphp
Commit 2dd20e37 authored by Mahmoud Aglan's avatar Mahmoud Aglan
Browse files
Options

docs: condense architecture-map protocol in CLAUDE.md 

Pre-existing uncommitted working-tree change, not part of the member search
work. Committed separately so the 478-line reduction stays visible in history.
Co-Authored-By: 's avatarClaude Opus 5 (1M context) <noreply@anthropic.com>
parent b7522599
Hide whitespace changes
Inline Side-by-side
Showing with 19 additions and 478 deletions
CLAUDE.md
View file @ 2dd20e37
......@@ -108,488 +108,29 @@ Connection params from `config/database.php` which reads from `.env`: `DB_HOST`,
---
# MODULE ARCHITECTURE MAP SYSTEM (MANDATORY)
## Architecture maps
This instruction overrides all implementation workflows.
`docs/architecture-maps/` holds notes on the modules that have been mapped so far
(Members, Subscriptions, Pricing, HR, Dashboard, plus `DEPENDENCY-GRAPH.md`).
Before modifying, creating, refactoring, deleting, or analyzing any module, you MUST first locate and read that module's Architecture Map.
They exist to save you rediscovery time, not to gate work. If a map exists for the
module you're touching, read it first — it's usually faster than crawling the code.
Trust the code over the map when they disagree, and correct the map when you learn
something that would have saved you time. If a map doesn't exist, just do the work;
write one only when the module is genuinely complex enough to be worth it, or when
asked.
Architecture Maps are not documentation.
## The live database is the source of truth
Architecture Maps are not notes.
Migrations lie — they're incomplete, superseded, and sometimes never ran. When
schema matters, inspect the live DB directly (tables, columns, indexes, constraints,
actual data). Never assume a column exists because a migration created it.
Architecture Maps are not reports.
## Fix causes, not symptoms
Architecture Maps are a mandatory knowledge system and source of truth used to maintain continuity across AI sessions and human developers.
A bug report describes a symptom; the file it mentions isn't necessarily where the
fix belongs. Find where the rule actually lives and fix it there, once — not a
patch per screen. Before changing a shared rule, check the other paths that hit it
(other controllers, API endpoints, cron, imports) so the fix holds everywhere.
Every development task must begin and end with the Architecture Map.
---
## REQUIRED WORKFLOW FOR EVERY TASK
Whenever a request affects a module:
### Step 1: Locate Architecture Map
Search for the module's Architecture Map at `docs/architecture-maps/{ModuleName}.md`.
If an Architecture Map exists:
* Read it completely.
* Use it as the starting context.
* Validate it against the current codebase.
* Update it with any new discoveries before making changes.
If an Architecture Map does NOT exist:
STOP.
Do not implement the requested change.
Do not start coding.
Do not make assumptions.
Instead, create the Architecture Map first using the Architecture Discovery Process described below.
Only after the initial Architecture Map exists may implementation begin.
---
## ARCHITECTURE MAPS ARE REQUIRED
No module is allowed to exist without an Architecture Map.
No feature is allowed to be modified without consulting its Architecture Map.
No task is considered complete until the Architecture Map has been updated.
Failure to update the Architecture Map means the task is incomplete.
---
## ARCHITECTURE DISCOVERY PROCESS
When creating a new Architecture Map:
You must build it incrementally.
Never attempt to understand the entire module in a single pass.
Instead:
1. Scan the module structure.
2. Identify major components.
3. Document findings.
4. Continue deeper analysis.
5. Append findings to the Architecture Map.
6. Refine existing entries.
7. Repeat until sufficient understanding exists.
The Architecture Map is a living document that grows over time.
It must never be regenerated from scratch.
It must be continuously improved and expanded.
---
## DATABASE TRUTH RULE
Migration files are NOT the source of truth.
Migration files may be outdated, incomplete, or inaccurate.
Whenever database structure matters:
* Connect directly to the database.
* Inspect actual tables.
* Inspect actual columns.
* Inspect actual relationships.
* Inspect actual indexes.
* Inspect actual constraints.
* Inspect actual views.
* Inspect actual triggers.
* Inspect actual procedures.
The live database is the source of truth.
If migrations conflict with the live database, trust the database.
Document actual database structure inside the Architecture Map.
---
## MANDATORY UPDATE RULE
Every code change must trigger an Architecture Map update.
After making changes:
1. Re-analyze affected components.
2. Identify new dependencies.
3. Identify changed dependencies.
4. Identify new workflows.
5. Identify changed workflows.
6. Update diagrams, flows, relationships, and references.
7. Save all findings into the Architecture Map.
This is mandatory.
There are no exceptions.
---
## ARCHITECTURE MAP PURPOSE
The Architecture Map exists to become the module's permanent knowledge graph.
Its purpose is to allow future AI sessions and human developers to:
* Understand the module quickly.
* Avoid re-discovering architecture.
* Avoid editing dead code.
* Avoid breaking live functionality.
* Avoid duplicating logic.
* Understand dependencies.
* Predict side effects.
* Implement changes safely.
* Reduce context usage and token consumption.
* Maintain continuity between development sessions.
The Architecture Map should eventually contain enough information that a developer or AI can understand how the module works before reading large portions of the codebase.
---
## REQUIRED CONTENT
Each Architecture Map must continuously document:
* Module purpose
* System responsibilities
* File structure
* Entry points
* Controllers
* Services
* Repositories
* Jobs
* Events
* Listeners
* Middleware
* API endpoints
* Database schema (from live DB, not migrations)
* Relationships
* Business rules
* User workflows
* Data flows
* State flows
* Permission model
* External integrations
* Internal integrations
* Dependency graphs
* Risk areas
* Legacy code
* Dead code
* Technical debt
* Change impact analysis
Most importantly:
Document relationships between systems, not just the systems themselves.
The Architecture Map must explain how everything connects.
---
## ENFORCEMENT
Before any task begins:
Verify Architecture Map exists at `docs/architecture-maps/{ModuleName}.md`.
If missing:
Create it first.
Before any task completes:
Update Architecture Map.
If Architecture Map is not updated:
The task is not complete.
Architecture Maps are mandatory project infrastructure and must be maintained with the same importance as production code.
---
# CROSS-MODULE DEPENDENCY GRAPH SYSTEM (MANDATORY)
Module Architecture Maps explain how a module works internally.
They do NOT fully explain how modules interact with each other.
To prevent incomplete implementations, missed cascading changes, broken workflows, hidden regressions, and cross-module inconsistencies, the system must maintain a second knowledge layer called the Cross-Module Dependency Graph.
This graph is a mandatory project artifact stored at `docs/architecture-maps/DEPENDENCY-GRAPH.md`.
It must be consulted before any implementation begins and updated after every implementation is completed.
---
## PURPOSE
The purpose of the Dependency Graph is to answer questions such as:
* If this field changes, what else breaks?
* If this workflow changes, what downstream systems are affected?
* If this API changes, who consumes it?
* If this table changes, what reports depend on it?
* If this permission changes, what modules are affected?
* If this event changes, what listeners will stop working?
* If this status changes, which automations fail?
* If this business rule changes, which workflows become invalid?
The Dependency Graph exists specifically to identify cascading changes.
---
## REQUIRED WORKFLOW
Before implementing any request:
Step 1: Read the affected Module Architecture Maps.
Step 2: Read the Cross-Module Dependency Graph.
Step 3: Identify all directly affected modules.
Step 4: Identify all indirectly affected modules.
Step 5: Build an Impact Analysis.
Step 6: Only then begin implementation.
No implementation should begin until dependency analysis has been completed.
---
## IF THE DEPENDENCY GRAPH DOES NOT EXIST
If the Dependency Graph does not exist:
STOP.
Do not begin implementation.
Create the Dependency Graph first.
Then continue with implementation.
---
## IMPACT ANALYSIS IS MANDATORY
For every requested change, produce an internal impact analysis identifying:
* **Direct Impact** — Files and systems being modified.
* **Upstream Dependencies** — Systems providing data or functionality.
* **Downstream Dependencies** — Systems consuming data or functionality.
* **Cascading Changes** — Changes required in other modules.
* **Risk Assessment** — Potential regressions.
* **Validation Requirements** — Areas requiring testing.
Implementation should never be performed until this analysis is complete.
---
## REQUIRED RELATIONSHIPS TO TRACK
The Dependency Graph must track:
* Module → Module Dependencies
* Database Dependencies (tables, views, procedures, shared entities)
* API Dependencies (providers and consumers)
* Event Dependencies (events, listeners, subscribers)
* Workflow Dependencies (business processes spanning multiple modules)
* Permission Dependencies (shared roles, policies, access controls)
* Reporting Dependencies (reports, dashboards, exports)
* Notification Dependencies (SMS, push notifications, alerts)
* Automation Dependencies (jobs, schedulers, workflows, triggers)
* Configuration Dependencies (settings, system options, rule engine keys)
---
## MANDATORY UPDATE RULE
Every implementation must update:
1. The affected Module Architecture Maps.
2. The Cross-Module Dependency Graph.
A task is not complete until both artifacts are updated.
---
## ENFORCEMENT
Before implementation:
Read Architecture Maps. Read Dependency Graph. Perform Impact Analysis.
After implementation:
Update Architecture Maps. Update Dependency Graph.
If any of these are missing or outdated, the task is incomplete.
The Dependency Graph is considered critical project infrastructure and must be maintained with the same importance as production code.
---
# DOMAIN LOGIC PRESERVATION PROTOCOL (MANDATORY)
The goal of every implementation is not to satisfy the request. The goal is to preserve and improve the correctness of the overall system.
A request describes a symptom. A request does not automatically describe the correct solution.
Before implementing any change, determine:
1. What behavior is being observed.
2. What behavior is expected.
3. What business rule is being violated.
4. Where that business rule truly belongs.
5. Which systems depend on that business rule.
Never assume the screen, form, API, controller, service, or file mentioned in the request is the correct place for the fix.
---
## ROOT CAUSE BEFORE FIX
Before modifying code, identify:
* Root cause.
* Business rule.
* Source of truth.
* Affected workflows.
* Affected modules.
Do not implement a fix until root cause analysis is complete.
---
## BUSINESS RULE FIRST
Every bug must be translated into a business rule.
Wrong: "The user can enter a negative quantity."
Correct: "Inventory quantities must never become negative."
The second statement describes a business rule. The first describes only one manifestation of the problem.
Always solve the business rule. Never solve only the symptom.
---
## SOURCE OF TRUTH RULE
Every business rule must have a source of truth (database constraint, domain service, validation service, workflow engine, permission system, state machine).
Before implementing a fix, identify where the source of truth should exist.
Whenever possible:
* Fix the source of truth.
* Avoid implementing duplicate validations in multiple locations.
* Avoid fixing only the UI.
* Avoid fixing only a single endpoint.
* Avoid fixing only a single workflow.
---
## SYSTEM-WIDE IMPACT REVIEW
Before implementing any change, ask:
* Where else can this action happen?
* Which APIs perform the same action?
* Which jobs perform the same action?
* Which imports perform the same action?
* Which automations perform the same action?
* Which modules perform the same action?
The solution must account for all valid entry points.
---
## NO LOCAL OPTIMIZATION
Never optimize for making a ticket pass. Never optimize for making a screen behave correctly in isolation. Never optimize for making a test pass.
Optimize for preserving the integrity of the entire system.
A fix that solves one screen while breaking architecture is a failed fix. A fix that solves one workflow while creating inconsistencies elsewhere is a failed fix.
---
## ARCHITECTURAL REVIEW REQUIRED
Before implementation, determine whether the proposed fix:
* Preserves existing business rules.
* Violates existing business rules.
* Introduces duplicate logic.
* Creates conflicting logic.
* Creates alternative sources of truth.
* Breaks system consistency.
If any of these occur, redesign the solution.
---
## MULTI-WORKFLOW VALIDATION
For every change, identify:
* Primary workflow.
* Secondary workflows.
* Administrative workflows.
* Automated workflows.
* Integration workflows.
Verify that the solution works consistently across all of them.
---
## IMPLEMENTATION DECISION RECORD
Before coding, document internally:
* **Issue:** What is happening.
* **Expected Behavior:** What should happen.
* **Business Rule:** Underlying rule.
* **Root Cause:** Actual cause.
* **Source of Truth:** Where rule should live.
* **Affected Modules:** List.
* **Affected Workflows:** List.
* **Chosen Solution:** Why this approach preserves system integrity.
* **Rejected Solutions:** Why simpler fixes were not used.
Only after this analysis may implementation begin.
---
## ENFORCEMENT
A change is considered incomplete if:
* It fixes only the symptom.
* It ignores root cause.
* It creates duplicate business logic.
* It introduces additional sources of truth.
* It does not evaluate downstream effects.
* It does not validate system-wide consistency.
The objective is not to satisfy the request. The objective is to preserve the correctness, consistency, and integrity of the entire ERP system.
Judgment call, not a procedure: a one-line view fix doesn't need an investigation.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment