AI-Cognitive-Leap/agnes-the-ai-analyst
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update CLAUDE.md with metrics, table registry, password auth

Browse source 
Add docs/metrics/ to project structure, Business Metrics and Table
Registry patterns to implementation details, password auth provider
to extensibility section, fix sync command for returning users.
This commit is contained in:
Petr 2026-03-10 23:05:03 +01:00
parent ad3b94c168
commit e35e602c59
1 changed files with 21 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
CLAUDE.md
View file

@ -56,6 +56,11 @@ Ask the user for:
│ ├── instance.yaml.example │ ├── instance.yaml.example
│ └── data_description.md.example │ └── data_description.md.example
├── docs/ # Documentation ├── docs/ # Documentation
│ └── metrics/ # Business metric YAML definitions
│ ├── revenue/ # Revenue metrics (total_revenue, AOV, etc.)
│ ├── customers/ # Customer metrics (count, repeat rate)
│ ├── marketing/ # Marketing metrics (ROI, CPA, conversion)
│ └── support/ # Support metrics (resolution time, CSAT)
└── tests/ # Test suite └── tests/ # Test suite
``` ```
@ -127,6 +132,7 @@ Pluggable data source connectors in `connectors/`:
Pluggable auth providers in `auth/`: Pluggable auth providers in `auth/`:
- **Google** (`google`): OAuth via Google - **Google** (`google`): OAuth via Google
- **Email** (`email`): Email magic link (itsdangerous token, no password needed) - **Email** (`email`): Email magic link (itsdangerous token, no password needed)
- **Password** (`password`): Username/password authentication
- **Desktop** (`desktop`): JWT for desktop app API - **Desktop** (`desktop`): JWT for desktop app API
- New provider = `auth/<name>/provider.py` implementing `AuthProvider` - New provider = `auth/<name>/provider.py` implementing `AuthProvider`
@ -151,7 +157,7 @@ uptime && free -h && df -h /data
## Returning Users ## Returning Users
When reopening the project in Claude Code: When reopening the project in Claude Code:
1. Sync latest data: `bash server/scripts/sync_data.sh` 1. Sync latest data: `rsync -avz --no-perms --no-group data-analyst:server/parquet/ ./server/parquet/`
2. Verify DuckDB: `ls -lh user/duckdb/analytics.duckdb` 2. Verify DuckDB: `ls -lh user/duckdb/analytics.duckdb`
3. Start analyzing with Claude Code 3. Start analyzing with Claude Code
@ -183,6 +189,20 @@ When reopening the project in Claude Code:
- Systemd files in `services/<name>/systemd/`, auto-discovered by `deploy.sh` - Systemd files in `services/<name>/systemd/`, auto-discovered by `deploy.sh`
- Services: telegram_bot, ws_gateway, corporate_memory, session_collector - Services: telegram_bot, ws_gateway, corporate_memory, session_collector
### Business Metrics Pattern
- YAML definitions in `docs/metrics/{category}/{metric}.yml` (list with one dict)
- `webapp/utils/metric_parser.py` - parses YAML, structures for modal UI, auto-discovers `sql_*` fields
- `webapp/app.py` `_load_metrics_data()` - scans metrics dir, groups by category, returns ordered list
- Catalog template renders dynamically via Jinja loop (no hardcoded metrics)
- Profiler links metrics to tables via `used_by_metrics` in `profiles.json`
- Production: metrics in instance repo deployed to `/data/docs/metrics/`
- Sample/dev: OSS repo `docs/metrics/` (10 e-commerce metrics)
### Table Registry Pattern
- `src/table_registry.py` - central CRUD for registered tables with atomic JSON persistence
- Audit logging for register/unregister operations
- Generates `data_description.md` from registry state
### Server Patterns ### Server Patterns
- Atomic JSON writes: `tempfile.mkstemp()` + `os.fchmod(fd, 0o660)` + `os.replace()` - Atomic JSON writes: `tempfile.mkstemp()` + `os.fchmod(fd, 0o660)` + `os.replace()`
- User home writes: `sudo /usr/bin/install -o {user} -g {user}` pattern - User home writes: `sudo /usr/bin/install -o {user} -g {user}` pattern