CLAUDE.md — flompt

⚠️ Mandatory Rules

NEVER commit or push _uploads/ directories — they exist at the root, in blog/, and in extension/. These folders contain raw uploaded files and must stay local only. They are in .gitignore; never override or bypass this rule.

Project Identity

flompt = flow + prompt — Visual AI Prompt Builder
URL : https://flompt.dev
Repo : https://github.com/Nyrok/flompt (monorepo)
Git email : nyrokgaming1@gmail.com

Stack

App : React 18 + TypeScript + React Flow v11 + Zustand + Vite (SPA in /app)
Blog : Next.js 16 + Tailwind CSS (static export in /blog, bilingual FR/EN)
Landing : Static HTML (in /landing)
Backend : FastAPI + Uvicorn (Python 3.12, port 8000)
Reverse Proxy : Caddy (auto-TLS Let's Encrypt, port 443)
AI : Anthropic Claude (pluggable, via httpx) + Groq (Llama Guard 4 prompt safety — currently DISABLED via PROMPT_GUARD_ENABLED=false in backend/.env)
MCP : FastMCP server (backend/app/mcp_server.py) exposes decompose/compile tools — registered on Glama.ai
Analytics : PostHog (EU region) — autocapture, session replay, heatmaps, error tracking
i18n : 10 languages (EN FR ES DE PT JA TR ZH AR RU) via LocaleContext + JSON files. Locale priority: URL path (/app/fr) → localStorage → default 'en'
SEO : Static locale pages generated post-build (app/scripts/generate-locale-pages.js). Each /app/[locale] serves a dedicated HTML with localized title, description, canonical and hreflang×10

Deployment Architecture

flompt.dev/
├── /           → landing/index.html (static, catch-all)
├── /app*       → app/dist/ (Vite SPA, handle_path strips /app)
├── /blog*      → blog/out/ (Next.js static export, handle_path strips /blog)
├── /api/*      → FastAPI :8000 (reverse_proxy)
└── /health     → FastAPI :8000 (reverse_proxy)

Monorepo Structure

/projects/flompt/
├── app/           # Vite React SPA (prompt builder)
│   ├── src/       # React components, styles, store
│   ├── dist/      # Production build (gitignored)
│   └── index.html # Entry point (base: /app)
├── blog/          # Next.js blog (static export)
│   ├── src/       # Pages, components, i18n
│   ├── content/   # Markdown posts (fr/ + en/) — slugs MUST match between locales
│   ├── out/       # Static export (gitignored)
│   └── next.config.ts  # basePath: /blog, output: export
├── landing/       # Static landing page
│   └── index.html
├── backend/       # FastAPI backend
│   ├── app/
│   └── .venv/
├── extension/     # Browser extension (Chrome + Firefox)
│   ├── Makefile   # make = both; make chrome; make firefox
│   └── dist/      # Built zips (gitignored)
├── docs/          # Documentation (block-types, chrome-extension, how-it-works, claude-code)
├── marketing/     # Marketing strategy, post drafts, activity logs
├── deploy.sh      # Full redeploy script (builds app+blog, restarts backend, reloads Caddy, health checks)
├── docker-compose.yml  # Local development (backend + frontend services)
├── supervisord.conf    # Production process manager (backend + Caddy)
├── watchdog.sh / keepalive.sh  # Supervisor health monitoring
├── Caddyfile      # Reverse proxy config
├── caddy          # Caddy binary (gitignored, 50MB)
└── CLAUDE.md      # This file

Commands

# App build (production)
cd /projects/flompt/app && npm run build

# Blog build (static export → out/)
cd /projects/flompt/blog && rm -rf .next && npm run build

# Backend
cd /projects/flompt/backend && .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

# Extension
cd /projects/flompt/extension
make              # icons + chrome + firefox (both zips)
make chrome       # dist/flompt-chrome.zip (Chrome Web Store)
make firefox      # dist/flompt-firefox.zip (Firefox AMO)
make icons        # regenerate PNG icons from icon.svg

# Caddy
cd /projects/flompt && ./caddy start --config Caddyfile
./caddy reload --config /projects/flompt/Caddyfile  # may hang — use workaround below if so
./caddy stop

# Caddy reload workaround (use if `caddy reload` hangs indefinitely)
/projects/flompt/caddy adapt --config /projects/flompt/Caddyfile 2>/dev/null \
  | curl -s -X POST "http://localhost:2019/load" -H "Content-Type: application/json" -d @-

# Full redeploy (preferred — handles everything)
bash /projects/flompt/deploy.sh

# Manual redeploy
cd /projects/flompt/app && npm run build
cd /projects/flompt/blog && rm -rf .next && npm run build
./caddy reload --config /projects/flompt/Caddyfile

# Health check
curl -sk -o /dev/null -w "%{http_code}" https://flompt.dev/
curl -sk -o /dev/null -w "%{http_code}" https://flompt.dev/app
curl -sk -o /dev/null -w "%{http_code}" https://flompt.dev/blog/en
curl -sk -o /dev/null -w "%{http_code}" https://flompt.dev/health

Template Library

Templates live in app/templates/<category>/<id>.json — one file per template, no TypeScript required.

Adding a template

Create a JSON file in the matching category folder. Schema:

{
  "id": "my-template",
  "category": "writing",
  "i18n": {
    "en": { "name": "My Template", "description": "One-sentence description." },
    "fr": { "name": "Mon template", "description": "Description en une phrase." }
  },
  "blocks": [
    { "type": "role",      "content": "You are a…" },
    { "type": "objective", "content": "Write a…"  }
  ]
}

Rules

id — unique, kebab-case, must match the filename (e.g. my-template.json)
category — one of: writing code marketing productivity design education sales data creative personal
blocks[].type — one of the 16 block types (see table below)
No positions, IDs, or React Flow internals needed — src/lib/templates.ts handles hydration via import.meta.glob
At least en and fr must be present in i18n; other locales fall back to en

How the loader works

app/src/lib/templates.ts uses import.meta.glob('../../templates/**/*.json', { eager: true }) to import all JSON files at Vite build time. hydrate() converts blocks[] → FlomptNode[] (positions + IDs auto-generated). Exports TEMPLATES, TEMPLATE_CATEGORIES, CATEGORY_COLORS, LOCALE_TO_LANG — no change needed in consuming components.

Block Types (16 total)

Ordered as assembled (TYPE_PRIORITY in assemblePrompt.ts):

#	Type	Icon	Color	Description
0	`document`	FileText	`#86efac`	XML grounding via `<document>` — always first
1	`role`	UserRound	`#c084fc`	AI persona / role
2	`tools`	Wrench	`#fb923c`	Callable functions and tools the AI can use
3	`audience`	Users	`#93c5fd`	Who the output is written for
4	`context`	Layers	`#94a3b8`	Background information
5	`environment`	Terminal	`#22d3ee`	System context: OS, paths, date, runtime
6	`objective`	Target	`#fbbf24`	Main task (what to DO)
7	`goal`	Flag	`#6ee7b7`	End goal and success criteria
8	`input`	LogIn	`#4ade80`	Data/variables provided to the AI
9	`constraints`	ShieldAlert	`#fb7185`	Rules and limits
10	`guardrails`	Lock	`#ef4444`	Hard limits and safety refusals — dashed border visual
11	`examples`	Lightbulb	`#c4b5fd`	Few-shot input/output pairs
12	`chain_of_thought`	Zap	`#fde68a`	Step-by-step reasoning instructions
13	`output_format`	LogOut	`#ff6b9d`	Expected response format — rounded bottom
14	`response_style`	Wand2	`#2dd4bf`	Structured style UI (verbosity/tone/markdown/LaTeX)
15	`language`	Languages	`#38bdf8`	Output language — always last

Removed blocks: chain_of_thought was temporarily removed then restored (Zap icon). format_control was removed — response_style now covers all formatting directives.

XML tag mapping (Claude format):

response_style → <format_instructions>
chain_of_thought → <thinking>
output_format → <output_format>
all others → same name as type

Make.com Integration

Architecture

No backend — all state lives in localStorage via a persisted Zustand store (flompt-make)
Entry point — "Send to Make.com" button in PromptOutput.tsx (web only, hidden when isExtension === true)
Panel — slide-in overlay from the right (MakeIntegration.tsx), mounted globally in App.tsx

Key files

File	Role
`app/src/store/makeStore.ts`	Persisted Zustand store — `webhookUrl` + `history` (last 10) saved to localStorage; `isPanelOpen`, `isSending`, `lastStatus` are transient
`app/src/components/MakeIntegration.tsx`	Full panel UI: webhook input, test button, prompt preview, send button, execution history, docs link

Payload sent to Make

{
  "prompt": "<assembled prompt text>",
  "format": "claude | chatgpt | gemini",
  "blockCount": 5,
  "source": "flompt",
  "sentAt": "<ISO string>"
}

CSS tokens

--make:       #6B5DFA   /* Make brand purple */
--make-2:     #5548d4   /* hover state */
--make-light: rgba(107, 93, 250, 0.15)
--make-glow:  rgba(107, 93, 250, 0.3)

Analytics events

make_panel_opened — user opens the panel
make_send_prompt — props: format, block_count, chars
make_send_success — webhook returned 2xx
make_send_error — props: reason

Validation rules

Webhook URL must be a valid http(s):// URL containing make.com
Send button disabled if: no valid webhook URL OR no compiled prompt
Test = POST with { _flompt_ping: true } — Make webhooks always return 200

MCP Server (Claude Code Integration)

flompt exposes its core tools as an MCP (Model Context Protocol) server so Claude Code and other MCP clients can decompose and compile prompts programmatically.

Key files

File	Role
`backend/app/mcp_server.py`	FastMCP server — exposes `decompose_prompt` and `compile_prompt` tools
`backend/mcp_stdio.py`	Stdio transport entry point for local MCP usage
`Dockerfile` (root)	Builds standalone MCP container image
`glama.json`	Glama.ai MCP registry schema

Tools exposed

decompose_prompt — breaks a raw prompt into structured blocks
compile_prompt — assembles blocks into Claude-optimized XML

Connection

# Remote (HTTP)
claude mcp add --transport http --scope user flompt https://flompt.dev/mcp/

# Local (stdio)
python backend/mcp_stdio.py

Deployment Infrastructure

Production process management

supervisord.conf manages two processes: flompt-backend (uvicorn) and flompt-caddy
watchdog.sh monitors supervisor, kills zombie uvicorn processes on port 8000
keepalive.sh auto-restarts supervisor if it stops

Docker (local dev / MCP)

docker-compose.yml — local dev with backend + frontend services
Root Dockerfile — standalone MCP server container (Python 3.12, runs mcp_stdio.py)
backend/Dockerfile — FastAPI container (Python 3.12 slim)

Analytics & Error Tracking (PostHog)

Project : EU region (https://eu.i.posthog.com)
MCP : installed via claude mcp add --transport http posthog https://mcp.posthog.com/mcp (user scope)
App : posthog-js initialized in src/lib/analytics.ts with capture_exceptions: true, session replay, heatmaps
Blog : posthog-js initialized in PostHogProvider.tsx with capture_exceptions: true
Error boundaries :
- App → ErrorBoundary.tsx calls posthog.captureException(error) + track('app_crash')
- Blog → src/app/error.tsx calls posthog.captureException(error)
Env vars : VITE_POSTHOG_KEY (app) / NEXT_PUBLIC_POSTHOG_KEY (blog)

Key UX Behaviours

Decompose button : disabled while decomposing, disabled if rawPrompt hasn't changed since last successful decomposition (lastDecomposedPrompt in Zustand store)
Assemble Prompt button : disabled if nodes.length === 0 OR compiledPrompt !== null (i.e. already compiled and no changes since — the store resets compiledPrompt to null on any node/edge mutation)
Star popup (StarPopup.tsx) : shown once (localStorage key flompt-star-popup-v1) after STAR_EVENT = 'flompt:action-completed' fires. Triggered by: compile, decompose, inject to AI (extension), FAB assembly (mobile). Rendered in ALL modes (web + extension).
Canvas overlays : CanvasBlockBar (left, vertically centered) + canvas-ctrl-bar (top-left: Clear → Undo → Redo)
Extension : isExtension flag from src/lib/platform.ts. After inject → dispatches STAR_EVENT. GitHub button replaces Share button everywhere (PromptOutput.tsx).
List View : second editing mode (toggle top-right). Horizontal toolbar (left: actions + compile, centre: block-type pills via CanvasBlockBar toolbar, right: view switcher). Each block is a card with header, editable textarea, ↑/↓ reorder, copy (duplicate), and delete buttons. Block names use t.blocks[type].label (live i18n, not stored label). Supports drag & drop from sidebar.
Hide / Show : Eye/EyeOff button on every block in both views. A hidden block is excluded from the assembled prompt. Rendered at reduced opacity (0.4 in List View, 0.35 in Canvas View).
Duplicate : Copy button on each card in List View — inserts a clone immediately after the source block with hidden: false.
Drag-over highlight : dashed accent outline (outline: 2px dashed var(--accent)) on both FlowCanvas (.flow-canvas--drag-over) and BlockListView (.block-list-view--drag-over) when a sidebar block is dragged over. onDragLeave on canvas checks relatedTarget to avoid flicker on children.
Decompose overlay : loading-overlay (Sparkles + dots + queue status) appears in both canvas and list view when isDecomposing === true. Same JSX, same CSS class, driven by the same Zustand state.
Tooltips : @radix-ui/react-tooltip (Shadcn Tooltip core) wraps all icon-only buttons app-wide. TooltipProvider in App.tsx. Component at components/ui/tooltip.tsx. All title= attributes removed from tooltipped buttons; aria-label kept for screen readers. CSS class .tooltip-content in styles.css.

Design / Branding

Logo : no icon, the title "flompt" in Caveat font (handwritten) is enough
Font titre : Caveat (Google Fonts), 700, accent color + glow
Font body : Inter (Google Fonts)
Accent : #FF3570 (app) / #ff4d82 (landing+blog)
Accent glow : text-shadow: 0 0 10px var(--accent-glow)
Theme : Mermaid-inspired dark (#1c1c1e)
Tagline : "flow + prompt = flompt"
SEO Language : English default (html lang="en", OG locale en_US). Locale pages at /app/[locale] use the correct lang + hreflang set
Firefox icon : FaFirefoxBrowser from react-icons/fa6 (app + blog). Landing uses inline SVG extracted from the same package.

Working Rules for Noryk

1. Before modifying CSS

Always check the cascade : desktop styles declared AFTER a mobile media query will override it
Put mobile overrides last or right after the block they override
Never change width/height to resize a positioned element → use transform: scale()
!important in React Flow code is necessary because RF injects its own inline styles
backdrop-filter without -webkit- prefix = broken on iOS Safari → use solid background instead

2. Before modifying the Caddyfile

Specific handle blocks MUST come before the catch-all handle (landing)
Use handle_path (not handle + uri strip_prefix) for sub-paths (/app, /blog)
handle_path /app* automatically strips the /app prefix from the path
After every Caddy change, test: landing /, app /app, blog /blog/en, health /health
caddy reload CLI can hang after adapting the config. If it does, use the API workaround: caddy adapt --config Caddyfile 2>/dev/null | curl -s -X POST http://localhost:2019/load -H "Content-Type: application/json" -d @-

3. Blog — Static Export

The blog uses output: "export" → generates static files in out/
NO Node server in production — Caddy serves the files directly
basePath: "/blog" → assets in the HTML are prefixed /blog/_next/...
handle_path /blog* strips /blog, files are found in out/_next/...
After every blog change: rm -rf .next && npm run build then check CSS/JS assets
Blog slugs MUST match between EN and FR — the locale switcher relies on identical filenames in content/posts/en/ and content/posts/fr/. The slug is ALWAYS the English filename (e.g. template-library.md in both locales, never bibliotheque-templates.md). Never translate the slug into French.

4. Before touching React Flow handles

Handles are positioned by React Flow with position: absolute + top/left
To resize without shifting position → use transform: scale()
connectOnClick={true} + ConnectionMode.Loose = click source then target, no drag

5. English only

The entire codebase must be in English — comments, docstrings, log messages, inline strings, CSS comments, shell scripts, Makefiles, config files
The only exception: i18n translation files (fr.json, translations.ts) and French blog post content (content/fr/) which are intentionally in French for end users
Never write French comments or strings anywhere else

5. Writing style (all surfaces)

No em dashes (—) or en dashes (–), ever. Use commas, periods, or rephrase.
Short, concise, straight to the point. No filler, no fluff, no corporate speak.
Sounds like a dev typing fast, not a polished essay or an AI-generated blog post.
Applies everywhere: marketing copy, README, landing page, blog, commit messages, comments, docs.

Anti-AI-slop rules (ref: tropes.fyi)

These patterns are instant tells of AI-generated text. Never use them:

No negative parallelism: "It's not X, it's Y" / "Not X. Not Y. Just Z." / "Not because X, but because Y" / "No X. No Y. Just Z."
No self-posed rhetorical questions: "The result? Devastating." / "The X? A Y."
No magic adverbs: quietly, deeply, fundamentally, remarkably, arguably, importantly, interestingly, notably, dramatically, radically, significantly
No AI vocabulary: delve, utilize, leverage, robust, streamline, harness, tapestry, landscape, paradigm, synergy, ecosystem, actionable, optimization
No "serves as" dodge: use "is", not "serves as" / "stands as" / "marks" / "represents"
No grandiose stakes inflation: a prompt builder is not "defining the next era of computing" or "separating frustrating AI from remarkable AI"
No false suspense: "Here's the kicker" / "Here's the thing" / "Here's where it gets interesting" / "Here's what changed everything"
No pedagogical voice: "Let's break this down" / "Let's unpack this" / "Think of it as..." / "Once you master these basics..."
No fractal summaries: don't intro what you'll say, say it, then summarize what you said
No signposted conclusions: "In conclusion" / "To sum up" / "In summary"
No invented concept labels: "validation-first" / "battle-tested prompt flow" / made-up compound terms
No "Despite its challenges...": don't acknowledge problems just to dismiss them immediately
No bold-first bullets in prose: only use bold-first in reference tables, not in marketing or blog content
No false vulnerability: no simulated self-awareness or polished "authenticity"
No vague attributions: "experts say" / "studies show" without specifics
No one-point dilution: say it once, well. Don't restate 6 ways across a page.
No superficial analyses: no tacked-on "-ing" phrases like "reflecting broader trends"
No AI tricolons: avoid the "structured, optimized, and ready to use" three-adjective AI cadence
No false ranges: "From X to Y" where X and Y aren't on a real spectrum

6. Understand intent before acting

If the request is ambiguous about WHAT (not how) → ask for clarification
Rule : if a change is destructive or structural (type swaps, architecture refactor), confirm intent

7. Before git add

Check .gitignore — *.png, caddy, dist/, .next/, node_modules/ are ignored
For images in app/public/, use git add -f
Never commit the caddy binary (50MB)
Never commit .env, credentials.json
NEVER add a Co-Authored-By line in commit messages — commits are signed by Noryk only

8. After each change

Always commit & push after any file modification — no exception
Always redeploy after each commit (bash /projects/flompt/deploy.sh)
Build the app/blog depending on what changed
Check routes via curl (landing, app, blog, health)
Never say "done" without having verified

9. Coherence across surfaces

Block types exist in: app/src/types/blocks.ts, assemblePrompt.ts, en.json, fr.json, backend/models/blocks.py, compiler.py, decomposer.py, ai_service.py, landing/index.html, docs/block-types.md, docs/claude-code.md, docs/how-it-works.md, blog posts (EN + FR)
When adding/removing a block → update ALL of the above. Don't forget blog FR articles.
Landing block count stat must stay in sync with actual block count (currently 16)

11. CustomSelect

All native <select> replaced by CustomSelect (components/CustomSelect.tsx) styled like ProjectSelector
Trigger variants via triggerClassName: csel-trigger--locale, csel-trigger--sm, csel-trigger--full, csel-trigger--lib
noReactFlow prop adds nodrag nopan classes + stopPropagation on click (use inside React Flow nodes)
dropUp prop for upward dropdown (e.g. near bottom of screen)
CSS classes: .csel, .csel-trigger, .csel-dropdown, .csel-option, .csel-option--active, .csel-chevron--open

12. SEO baseline

Blog: all pages have og:image, twitter:card: summary_large_image, explicit twitter:images
Blog root layout: og:locale: "fr_FR" as default fallback
Blog sitemap: uses real post dates (post.date) not new Date()
Blog robots.txt: references both /blog/sitemap.xml and /sitemap.xml
Landing privacy.html + terms.html: og:image + twitter:card added
App index.html: twitter:description + full hreflang set (10 locales + x-default)

10. Backend — known pitfalls

idb package must be installed in app/ (npm install idb) — required by src/lib/db.ts (Context Memory + Version History). If missing, tsc fails and npm run build produces no dist/.
AI_MODEL in backend/.env must be a valid model ID for the configured provider. For Groq: use llama-3.3-70b-versatile (supports response_format: json_object). The value openai/gpt-oss-120b is invalid on Groq.
Backend restart — supervisorctl is not available in this environment. To restart the backend, find the PID via cat /proc/*/cmdline | tr '\0' ' ' and kill -9 <pid>, then relaunch with cd /projects/flompt/backend && nohup .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 > /tmp/flompt-backend.log 2>&1 &. pkill/fuser are unreliable here.
New routers won't load until the backend process is fully restarted — verify with curl -s http://localhost:8000/openapi.json | python3 -c "import sys,json; [print(p) for p in json.load(sys.stdin)['paths']]"

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md — flompt

⚠️ Mandatory Rules

Project Identity

Stack

Deployment Architecture

Monorepo Structure

Commands

Template Library

Adding a template

Rules

How the loader works

Block Types (16 total)

Make.com Integration

Architecture

Key files

Payload sent to Make

CSS tokens

Analytics events

Validation rules

MCP Server (Claude Code Integration)

Key files

Tools exposed

Connection

Deployment Infrastructure

Production process management

Docker (local dev / MCP)

Analytics & Error Tracking (PostHog)

Key UX Behaviours

Design / Branding

Working Rules for Noryk

1. Before modifying CSS

2. Before modifying the Caddyfile

3. Blog — Static Export

4. Before touching React Flow handles

5. English only

5. Writing style (all surfaces)

Anti-AI-slop rules (ref: tropes.fyi)

6. Understand intent before acting

7. Before git add

8. After each change

9. Coherence across surfaces

11. CustomSelect

12. SEO baseline

10. Backend — known pitfalls