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 the Write tool 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. 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.
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

Project Styles

When creating new modules, you need to match the visual style of the existing project. To avoid re-exploring modules every time:

1. If docs/project-styles.md exists → read it. It contains the project's color palette, typography, spacing, and design patterns. Use it directly.
2. If it does NOT exist and there are 3+ modules → explore the existing modules to understand the style, then generate docs/project-styles.md with a summary for future use.
3. If it does NOT exist and there are few modules → create the module based on the user's description without exploring. The style will be defined as modules are created.

When exploring modules for style reference:

• Only look at modules that have a builder.json file (these are builder modules)
• Skip modules whose directory name starts with custom- (these are general sections, not visual modules)
• Read index-base.tpl and style.css of 3-4 representative modules
• Summarize: color palette, typography, spacing, Tailwind patterns, common CSS classes, design conventions

When generating docs/project-styles.md, include:

• Primary/secondary/accent colors (hex values)
• Font families and sizes used
• Spacing scale (padding/margin patterns)
• Common Tailwind classes and custom CSS patterns
• Button styles, card styles, section layouts
• Any recurring design patterns (gradients, shadows, borders, etc.)

Update docs/project-styles.md after creating a module if the project has grown significantly since the last update (e.g. 5+ new modules).

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: create_module → add_module_to_record → set_module_config_vars → images
• Edit module: read vars → edit index-base.tpl → compile_module
• Add images: get_module_config_vars → upload_record_image (fieldName from builder.json relations)
• 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/mcp-tools-reference.md — MCP tools reference, available tools, workflows