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 or HTTP requests to localhost:8080

Project Structure

.
├── template/estandar/
│   ├── modulos/          # Builder modules (visual components)
│   │   └── <module-id>/
│   │       ├── index-base.tpl    # Twig template (source)
│   │       ├── index.tpl         # Compiled template (auto-generated, do NOT edit)
│   │       ├── style.css         # Module styles
│   │       └── script.js         # Module JavaScript
│   ├── 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), CSS, and JS. Modules are placed on pages via the drag-and-drop builder.

See docs/modular-system.md for detailed rules.

General Sections

Reusable layout blocks (header, footer, sidebars) that appear across multiple pages. They use the same Twig engine as modules but serve a structural purpose.

See docs/modular-system.md for details.

Hooks (hooks/)

PHP files that execute server-side logic at specific points: before/after page load, on form submission, on API calls, scheduled tasks, etc. Hooks extend the CMS behavior without modifying the core.

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/.env or docker-compose.yml for the mapped port (usually 3307+)
• Credentials: Read from .docker/.env:
  • DB_USERNAME
  • DB_PASSWORD
  • DB_DATABASE

You can also exec into the container:

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

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.

If you need to understand core behavior (Twig filters, CmsApi methods, routing, etc.), the web-base path can be obtained from the plugin settings. Do NOT modify web-base files — they are shared across all projects.

Documentation

• docs/modular-system.md — Modules, general sections, Twig syntax, builder vars, custom filters
• docs/hooks-and-api.md — PHP hooks, CmsApi, CocoDB, database operations
• docs/builder-fields.md — Builder field types, c-form, c-if/c-for/c-class, data-field-type