docs: replace template CLAUDE.md with repo-specific version

2026-06-22 13:48:08 +00:00
parent 2c2ca32c3c
commit 130c192096
1 changed files with 43 additions and 36 deletions
@@ -1,47 +1,54 @@
-# CLAUDE.md
+# MokoSuiteInsight

-This file provides guidance to Claude Code when working with this repository.
+Real-time dashboards, KPI monitoring, and alerting for Joomla 6. Chart.js 4 rendering, pluggable data sources.

-## Project Overview
-
-**Template-Joomla** -- Unified Joomla extension scaffolding templates — plugin, template, module, component, package, library
+## Quick Reference

 | Field | Value |
 |---|---|
-| **Platform** | template |
-| **Language** | Markdown |
-| **Default branch** | main |
-| **License** | GPL-3.0-or-later |
-| **Wiki** | [Template-Joomla Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-Joomla/wiki) |
-| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |
-
-## Common Commands
-
-```bash
-make build        # Build the project
-make lint         # Run linters
-make validate     # Validate structure
-make release      # Full release pipeline
-make minify       # Minify CSS/JS assets
-make clean        # Clean build artifacts
-```
-
-```bash
-composer install  # Install PHP dependencies
-```
+| **Package** | `pkg_mokosuitesight` |
+| **Layer** | Standalone (auto-detects installed modules) |
+| **Language** | PHP 8.3+ / JavaScript (Chart.js 4) |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+| **Wiki** | [MokoSuiteInsight Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteInsight/wiki) |

 ## Architecture

-This is a project template. Files are copied when creating new repos.
- Edit files here to change defaults for new projects
- `.mokogitea/workflows/` -- CI/CD workflow templates
- `Makefile` -- build targets inherited by new projects
+Joomla **package** (`pkg_mokosuitesight`) — standalone module, auto-discovers installed MokoSuite data sources.
+
+### Optional Integrations
+- Any MokoSuite module — auto-detected via `class_exists()` for data source registration
+- Built-in sources: `crm.contact_count`, `crm.deals_pipeline`, `crm.revenue_monthly`, `pos.daily_sales`, `hrm.headcount`
+
+### Helpers (5)
+- `DashboardHelper` — CRUD, widget management, user dashboards
+- `DataSourceHelper` — pluggable metric connectors, query interface
+- `AlertHelper` — threshold monitoring, fire/acknowledge, cooldown
+- `WidgetHelper` — Chart.js data formatting (counter, line, bar, pie, gauge, table, sparkline, heatmap, funnel)
+- `ExportHelper` — CSV from any widget, dashboard snapshot logging
+
+### Key Patterns
+- Data sources register themselves — each MokoSuite module provides a `DataSource` class
+- AlertHelper skips non-scalar data sources (prevents false triggers on list-type sources)
+- Widget rendering is server-side data + client-side Chart.js
+
+## Source Directory
+
+- `source/pkg_mokosuitesight.xml` — package manifest
+- `source/packages/` — sub-extensions

 ## Rules

- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, or `*.min.css`/`*.min.js`
- **Attribution**: use `Authored-by: Moko Consulting` in commits
- **Branch strategy**: develop on `dev`, merge to `main` for release
- **Minification**: handled at build time (CI) and runtime (MokoMinifyHelper for Joomla templates)
- **Wiki**: documentation lives in the Gitea wiki, not in `docs/` files
- **Standards**: this repo follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/`
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoCLI/wiki)
+- **Changelog**: `[Unreleased]` only — release system assigns versions
+
+## Coding Standards
+
+- PHP 8.3+ / Joomla 6 patterns
+- `$this->getDatabase()` in models, `Factory::getContainer()->get(DatabaseInterface::class)` in helpers
+- `Factory::getApplication()->getIdentity()` for user
+- Chart.js config passed as JSON from PHP — no inline JS in views