acai-scaffold/CLAUDE.md

# Acai CMS — Project Instructions

This is an Acai CMS website project. Follow these instructions when working with the codebase.

## Environment

- The site runs in Docker, typically at **http://localhost:8080**
- You can make HTTP requests to test pages, APIs, or form submissions
- If you need to inspect the live site, use browser tools (Playwright MCP) or HTTP requests to localhost:8080

## Project Structure

```
.
├── template/estandar/
│   ├── modulos/          # Builder modules (visual components)
│   │   └── <module-id>/
│   │       ├── index-base.tpl    # Twig template (source — EDIT THIS)
│   │       ├── style.css         # Module styles
│   │       └── script.js         # Module JavaScript
│   │       ├── index.tpl         # Compiled (auto-generated, do NOT edit)
│   │       ├── index-twig.tpl    # Compiled (auto-generated, do NOT edit)
│   │       └── builder.json      # Compiled builder vars (auto-generated, do NOT edit)
│   ├── css/              # Global CSS
│   └── js/               # Global JavaScript
├── hooks/                # PHP hooks (server-side logic)
├── cms/
│   ├── data/schema/      # Database table schemas (JSON)
│   ├── lib/plugins/      # CMS plugins
│   └── uploads/          # Uploaded media files
├── .acai                 # Project config (domain, tokens, DB credentials)
├── .docker/
│   ├── .env              # Docker environment (DB credentials)
│   ├── docker-compose.yml
│   ├── tunnel-url.txt    # Public tunnel URL (if active)
│   └── bore-db-url.txt   # Database tunnel URL (if active)
└── database.sql          # Database dump
```

## Key Concepts

### Modules (`template/estandar/modulos/`)
Visual components that the site builder uses. Each module is a self-contained unit with its own template (Twig + Acai attributes), CSS, and JS. Modules are placed on pages via the drag-and-drop builder. The editable file is always `index-base.tpl`.

- Include other modules: `<module_id :param1="value1"></module_id>`
- Each module instance gets a unique `section_id` variable for anchors/scoping
- Use `interno` variable to detect CMS editor mode vs public view

See [docs/modular-system.md](docs/modular-system.md) for detailed rules.

### General Sections
Database-backed templates (headers, footers, record views) that use the `thisrecord` variable to access record fields. They use the same Twig + Acai attribute engine as modules.

- Upload fields return arrays: `thisrecord.image[0].urlPath`
- Foreign keys use `_num` suffix: `category_num`

See [docs/modular-system.md](docs/modular-system.md) for details.

### Hooks (`hooks/`)
PHP files that execute server-side logic. Triggered by:
- Twig filter: `'hooks/module_id/' | hook({param: value})`
- HTML tag: `<hook result="var" endpoint="/hooks/module_id/" :param="value"></hook>`
- JavaScript: `CmsApi.hook('/hooks/module_id/', {param: value}, callback)`
- Form action: via `c-form` attribute

See [docs/hooks-and-api.md](docs/hooks-and-api.md) for usage.

## Database Access

When the site is running in Docker, you can connect to the database:

- **Host:** `127.0.0.1`
- **Port:** Check `.docker/docker-compose.yml` for the mapped port (usually 3307+)
- **Credentials:** Read from `.docker/.env`:
  - `DB_USERNAME`
  - `DB_PASSWORD`
  - `DB_DATABASE`

```bash
docker exec -it dw-<project-name>-db mysql -u root -p<password> <database>
```

**Important:** Table names in CmsApi/Twig do NOT use the `cms_` prefix. The primary key is always `num`, never `id`.

## Acai Core (web-base)

The project workspace contains only the **customization layer** (modules, hooks, schemas, uploads). The CMS core (routing, rendering engine, admin panel, APIs) lives in a separate directory called **web-base** that is mounted as a Docker volume.

The web-base path can be obtained via: `GET http://localhost:9090/api/web-base-path`

Do NOT modify web-base files — they are shared across all projects.

## Critical Rules

1. **Before working with any area (hooks, modules, templates, CSS/JS, etc.), read the corresponding documentation in `docs/` first.** Do not guess or assume — always consult the docs before taking action.
2. Only edit `index-base.tpl` in modules — `index.tpl`, `index-twig.tpl`, and `builder.json` are auto-generated
3. **After editing any `index-base.tpl`, ALWAYS call the `compile_module` MCP tool** to compile the module/section. This is mandatory — without compilation, changes won't take effect in the CMS.
4. Use Twig **filters** (with `|`), never Twig functions
5. Table names without `cms_` prefix everywhere
6. Primary key is `num`, never `id`
7. Upload fields are arrays — access with `[0].urlPath`
8. Tailwind CSS as primary styling, custom CSS scoped with BEM when needed
9. Twig concatenation uses `~` operator: `'value=' ~ variable`
10. `enlace` (link) fields already include slashes
11. **File hooks (`hooks/*.php`) do NOT inject variables.** Always read params manually: `$params = json_decode(file_get_contents('php://input'), true) ?: [];` — Only module hooks (`modulos/*/hook.php`) receive variables directly.
12. **`tipo` is a reserved variable.** The `.htaccess` injects `tipo=barra` on every request. Never use `tipo` as a hook parameter name — it gets overwritten, causing 404s. Use `account_type`, `user_tipo`, etc.

## Documentation

- [docs/modular-system.md](docs/modular-system.md) — Modules, general sections, global variables
- [docs/builder-fields.md](docs/builder-fields.md) — Builder field types, Acai attributes, c-form, components
- [docs/twig-filters.md](docs/twig-filters.md) — Twig filters reference (get, hook, module, queryDB, etc.)
- [docs/hooks-and-api.md](docs/hooks-and-api.md) — PHP hooks, CmsApi, CocoDB, record creation
- [docs/css-js-conventions.md](docs/css-js-conventions.md) — CSS/JS/Vue 3, Tailwind, BEM, native components
- [docs/quick-reference.md](docs/quick-reference.md) — Cheat sheet: domain rules, field types, filters
- [docs/production-patterns.md](docs/production-patterns.md) — Real production patterns (header, zigzag, FAQ, forms)
- [docs/vue-builder-rules.md](docs/vue-builder-rules.md) — CMS-VUE rules (tabs, colorpicker, components)
- [docs/vue-builder-examples.md](docs/vue-builder-examples.md) — Vue builder examples (Banner Slideshow, etc.)