MaalFlows Agent

Purpose: maintain the MaalFlows live chat widget and admin app.

Project Shape

Main application file: server.js.
Frontend assets: public/widget.js, public/admin.js, public/admin.html, public/preview.html.
CSS source: src/styles/tailwind.css imports specialized admin styles from src/styles/admin.css and builds the single served stylesheet public/tailwind.css.
Runtime: Node.js without a framework, SQLite through better-sqlite3.
Local check command: npm.cmd run check.
Production app is proxied by nginx on app.black-week.cz to 127.0.0.1:3400.

Work Rules

Read the relevant code before editing.
Keep changes small and focused on the user's request.
Do not touch .agents/sogo-mail-filter-agent.md or docs/mail-sogo-* files unless the task is explicitly about SOGo mail filters.
Preserve existing user changes. Do not reset, checkout, or delete unrelated work.
For language/translation changes, protect conversation-level customer language from short greetings, product names, SKUs, colors, and other language-neutral text.

Verification

Before finishing a code change, run:

npm.cmd run verify

verify runs syntax checks, Tailwind CSS build, and Playwright UI smoke tests. If the change is documentation-only, npm.cmd run check is sufficient, but say that explicitly.

For any meaningful layout or styling change:

Start or let Playwright start the local server.
Use Playwright for visual inspection instead of judging only from code.
Check at least desktop and mobile viewports when the UI surface can appear on both.
Inspect screenshots for overlap, broken spacing, unreadable text, and inconsistent controls.
Keep normal Playwright runs headless. Use headed/visible browser only while diagnosing a UI or scraping/browser-automation failure.
If browser automation is added for external sources, choose the browser engine from source configuration, behave slowly and politely, and do not use Playwright to bypass site protections.

Playwright scripts:

npm.cmd run test:ui
npm.cmd run test:ui:headed

Playwright screenshots and reports are ignored by Git.

TailwindCSS

TailwindCSS is the main styling system for new and refactored UI. The source file is src/styles/tailwind.css, built to public/tailwind.css with:

npm.cmd run build:css

Rules:

Treat src/styles/tailwind.css as the master style source from now on.
src/styles/admin.css contains legacy/specialized admin CSS that is imported into the Tailwind build. Do not create or link standalone CSS files for app UI; migrate repeated UI patterns into src/styles/tailwind.css component classes instead.
New screens and redesigned sections should be built with Tailwind utility classes or reusable classes from @layer components.
Prefer reusable Tailwind component classes in @layer components over one-off CSS for repeated controls.
Repeated controls should share the same structure: icon before text, centered text, chevron on the right, consistent icon size/color/alignment, height, padding, border, radius, hover, and focus states.
Panel top bars should share height, border, background, text color, and button styling.
If a master style exists, extend it instead of creating a second variant of the same control.
Dark/light theme changes must apply consistently to sidebars, panels, tables/grids, modals, inputs, and controls.
Data-heavy UI should stay compact, scannable, responsive, and avoid an Excel-like look unless explicitly required.
Wide data workspaces should allow horizontal scrolling when content is wider than the viewport.
Before finishing a UI component change, check similar components for style consistency.

Git Workflow

Project remote:

https://git.ma-al.com/rajch_ales/MaalFlows.git

The main branch is main.

After each completed project code change:

Review git diff.
Stage only files that belong to the change.
Commit with a concise message.
Push the current branch to origin.
Report what was changed, what was verified, and whether the push succeeded.

Do not stage unrelated untracked files such as historical audits, screenshots, exports, or mail-filter documentation unless the user explicitly asks for them.

If Git authentication is needed, this project follows the same HTTPS credential style as D:\Codex\01-projekty\catalog-meaker-by-magic-ai: read GIT_USERNAME and GIT_PASSWORD from that project's local .env only for the command that needs them. Never print those values, commit them, save them into origin, or leave credentials embedded in Git config.

Production Update

After a successful push, update the production server.

Production details:

Host: app.black-week.cz
SSH user: root
SSH key: C:/Users/DELL/.ssh/druhakapitola_hetzner
App directory: /var/www/maalflows
PM2 process: maalflows
Public URL: https://app.black-week.cz/admin

Deploy workflow:

SSH to root@app.black-week.cz with the druhakapitola_hetzner key.
In /var/www/maalflows, check git status --short first. Stop if there are unexpected local changes.
Ensure server origin is https://git.ma-al.com/rajch_ales/MaalFlows.git.
Fetch origin main. If HTTPS credentials are required, provide them via a one-command temporary credential helper from the local catalog project's .env; do not store credentials on the server.
Run git merge --ff-only FETCH_HEAD.
Run npm install --omit=dev.
Run npm run check.
Run pm2 restart maalflows.
Run pm2 save.
Verify:

cd /var/www/maalflows && git status --short
cd /var/www/maalflows && git log -1 --oneline
pm2 describe maalflows
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://127.0.0.1:3400/admin
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://127.0.0.1:3400/widget.js
curl -k -s -o /dev/null -w '%{http_code} %{content_type}\n' https://app.black-week.cz/admin

Expected verification: PM2 status online, local /admin and /widget.js return 200, public HTTPS /admin returns 200, and the server worktree is clean.

6.0 KiB Raw Blame History