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 for detailed rules.

Pages

Every record with an enlace field is a page. Pages are either Builder (modular) or Standard:

• Builder: controlador = cms/lib/plugins/builder_saas/controlador.php — content via modules
• Standard: controlador = cms/lib/plugins/builder_saas/controlador_tabla.php — content in record fields

Critical: Never change enlace or controlador of existing pages unless explicitly asked.

See docs/pages-and-records.md for full details.

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 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 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

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. NEVER use mkdir to create directories. Instead, use acai-write to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the index-base.tpl file.
3. Only edit index-base.tpl in modules — index.tpl, index-twig.tpl, and builder.json are auto-generated
4. Editing or creating any index-base.tpl through acai-write or acai-line-replace triggers automatic compilation. Only use compile_module manually if you need to re-run compilation without changing the file.
5. Use Twig filters (with |), never Twig functions
6. Table names without cms_ prefix everywhere
7. Primary key is num, never id
8. Upload fields are arrays — access with [0].urlPath
9. Tailwind CSS as primary styling, custom CSS scoped with BEM when needed
10. Twig concatenation uses ~ operator: 'value=' ~ variable
11. enlace (link) fields already include slashes — NEVER modify an existing enlace unless explicitly asked
12. NEVER modify the controlador field of existing records — it defines whether a page is Builder or Standard

MCP Tools

This project has MCP tools for managing modules, records, media, and more. Before starting any task, consult the tools reference for the correct workflow.

See docs/mcp-tools-reference.md for the complete list of available tools and step-by-step workflows.

Key workflows:

• Create module: Read docs/module-creation-guide.md first → create files with acai-write / refine with acai-line-replace → automatic compile on index-base.tpl → add_module_to_record (returns sectionId) → set_module_config_vars (returns uploadFields) → images via uploadFields
• Edit module: acai-view → acai-line-replace (or acai-write for full rewrites) → automatic compile on index-base.tpl
• Add images: use uploadFields from set_module_config_vars response → upload_record_image
• Generate images: generate_image → upload_record_image with returned URL

Documentation

• docs/modular-system.md — Modules, general sections, global variables
• docs/builder-fields.md — Builder field types, Acai attributes, c-form, components
• docs/twig-filters.md — Twig filters reference (get, hook, module, queryDB, etc.)
• docs/hooks-and-api.md — PHP hooks, CmsApi, CocoDB, record creation
• docs/css-js-conventions.md — CSS/JS/Vue 3, Tailwind, BEM, native components
• docs/quick-reference.md — Cheat sheet: domain rules, field types, filters
• docs/production-patterns.md — Real production patterns (header, zigzag, FAQ, forms)
• docs/vue-builder-rules.md — CMS-VUE rules (tabs, colorpicker, components)
• docs/vue-builder-examples.md — Vue builder examples (Banner Slideshow, etc.)
• docs/pages-and-records.md — Page types (Builder vs Standard), sections, visibility, critical rules
• docs/module-creation-guide.md — Module creation workflow, style reference, field types
• docs/mcp-tools-reference.md — MCP tools reference, available tools, workflows