server/AGENTS.md

Rama master · réplica de lectura del repositorio original.

# Chartbrew Server (Backend) – Agent Documentation

This is the index for agent-oriented documentation. Each topic is detailed in separate files under `docs/agents/`.

## Quick Navigation

### Core Architecture
- [Runtime and Architecture](docs/agents/runtime-and-architecture.md) - Entry points, settings, routing, models
- [Data Visualization Pipeline](docs/agents/data-visualization-pipeline.md) - Connection → DataRequest → Dataset → Chart flow
- [Filtering Guide](docs/agents/filtering-guide.md) - Runtime filter sources, merge rules, normalization, and execution

### Features and Flows

- [AI Usage Records](docs/agents/ai-usage.md) - Provider accounting and Cloud billing hooks
- [Source Execution Records](docs/agents/source-execution.md) - Source counting, callbacks, attribution, retention and setup
- [User Authentication](docs/agents/user-authentication.md) - Signup, login, 2FA, password reset, email updates
- [Platform Settings](docs/agents/platform-settings.md) - Platform-admin access, safe configuration registry, and runtime overrides

### Development
- [Testing Guide](docs/agents/testing-guide.md) - Test framework, DB lifecycle, integration tests

## Document Purpose

These documents are optimized for LLM agents to:
- Understand the complete system architecture
- Identify edge cases before making changes
- Find relevant code quickly
- Preserve critical behaviors during refactors

## Document Status

| Document | Status | Last Updated |
|----------|--------|--------------|
| Runtime and Architecture | ✓ Current | 2025-01-XX |
| Data Visualization Pipeline | ✓ Current | 2025-01-XX |
| Filtering Guide | ✓ Current | 2026-04-14 |
| User Authentication | ✓ Current | 2025-01-XX |
| Platform Settings | ✓ Current | 2026-08-12 |
| Testing Guide | ✓ Current | 2025-01-XX |

## Contributing to Agent Docs

When adding documentation:
1. Create themed files in `docs/agents/`
2. Keep files focused (< 500 lines each)
3. Update this index with links
4. Use Mermaid diagrams for complex flows
5. Include specific code pointers (file paths + line numbers)
6. Document edge cases and critical behaviors