Contributing to flompt

Contributing to flompt

Thanks for wanting to contribute! flompt is open-source and MIT licensed — PRs, bug reports, and feature ideas are all welcome.

Table of Contents

• Getting started
• Project structure
• Development workflow
• Code style
• Adding a block type
• Adding a language
• Submitting a PR

---

Getting started

**Requirements:** Node.js 18+, Python 3.12+

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/flompt.git
cd flompt

# 2. Start the backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # optional: add your Anthropic/OpenAI key
uvicorn app.main:app --reload --port 8000

# 3. Start the frontend (new terminal)
cd app
npm install
npm run dev             # → http://localhost:5173

The heuristic decomposer works without an API key — you don't need one to develop most features.

---

Project structure

flompt/
├── app/          # React 18 + Vite frontend (TypeScript)
│   └── src/
│       ├── components/   # UI components
│       ├── i18n/         # 10 locale JSON files
│       ├── lib/          # assemblePrompt, analytics, platform
│       ├── services/     # HTTP client (axios)
│       ├── store/        # Zustand state
│       └── types/        # TypeScript types (blocks.ts)
├── backend/      # FastAPI backend (Python)
│   └── app/
│       ├── routers/      # decompose, compile
│       └── services/     # ai_service, compiler, decomposer
├── blog/         # Next.js blog (static export)
├── extension/    # Chrome / Firefox / Safari MV3 extension
├── docs/         # GitBook documentation
└── landing/      # Static landing page

For a deeper dive, read [`CLAUDE.md`](CLAUDE.md) — it covers design rules, block ordering, CSS conventions, and deployment architecture.

---

Development workflow

1. **Create a branch** from `master`:

   git checkout -b feat/my-feature

2. **Make your changes** — keep commits focused and atomic.

3. **Test locally** before opening a PR:

   • Frontend: npm run build in app/ should succeed with no errors
   • Backend: your new route/service should handle edge cases gracefully
   • If you touched the extension: test on at least one browser

4. **Open a PR** — the template will guide you.

---

Code style

• TypeScript everywhere in the frontend. New types go in app/src/types/blocks.ts.
• No inline styles — use CSS classes. New design tokens go in :root in app/src/styles.css.
• No console.log in production code paths.
• English only in source code (comments, variable names, function names). UI strings live in i18n JSON files.
• Backend: we use Ruff for linting. Run ruff check app/ before committing.

---

Adding a block type

Block types are defined in two places:

1. **`app/src/types/blocks