Add contributing guidelines, feature flag utilities, and route integrity tests

CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to SaaS-PDF
+
+## Safety Rules
+
+These rules are **non-negotiable**. Every PR must comply.
+
+### 1. Never Delete Existing Routes
+
+All routes are registered in `frontend/src/config/routes.ts`. This file is the canonical source of truth. The route safety test (`routes.test.ts`) verifies that every registered route exists in `App.tsx`.
+
+- **Adding a route:** Append to `routes.ts` → add `<Route>` in `App.tsx`
+- **Removing a route:** ❌ NEVER. Deprecate by redirecting instead.
+
+### 2. Never Modify Existing Working Tools
+
+Each tool lives in its own file under `frontend/src/components/tools/`. Do not change a tool's:
+
+- Public API (props, accepted file types, output format)
+- Route path
+- Backend endpoint it calls
+
+If you need to change behavior, add a new option behind a feature flag.
+
+### 3. Never Break Existing Tests
+
+Run the full test suites before pushing:
+
+```bash
+# Frontend
+cd frontend && npx vitest run
+
+# Backend
+cd backend && python -m pytest tests/ -q
+```
+
+If a test fails after your change, **fix your code**, not the test — unless the test itself is wrong (and you explain why in the PR).
+
+### 4. Add New Functionality in Isolated Modules
+
+- New tools → new file under `components/tools/`
+- New pages → new file under `pages/`
+- New backend routes → new file or append to existing route file
+- New services → new file under `services/` or `utils/`
+
+Never add new logic inline to existing tool components. Keep changes isolated so they can be reverted independently.
+
+### 5. Use Feature Flags When Needed
+
+#### Backend
+
+Feature flags are defined in `backend/config/__init__.py`:
+
+```python
+FEATURE_EDITOR = os.getenv("FEATURE_EDITOR", "true").lower() == "true"
+```
+
+Check them in routes:
+
+```python
+from flask import current_app
+if not current_app.config.get("FEATURE_EDITOR"):
+    return jsonify(error="Feature disabled"), 403
+```
+
+#### Frontend
+
+Feature flags are defined in `frontend/src/config/featureFlags.ts`:
+
+```typescript
+import { isFeatureEnabled } from '@/config/featureFlags';
+
+if (isFeatureEnabled('EDITOR')) {
+  // render the tool
+}
+```
+
+Set via environment variables:
+
+```env
+VITE_FEATURE_EDITOR=true    # enabled (default)
+VITE_FEATURE_OCR=false      # disabled
+```
+
+---
+
+## Development Workflow
+
+### Branch Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature | `feature/tool-name` | `feature/pdf-merger` |
+| Fix | `fix/issue-description` | `fix/ocr-language-flag` |
+| SEO | `feature/seo-*` | `feature/seo-content` |
+
+### PR Checklist
+
+- [ ] No existing routes removed (checked by `routes.test.ts`)
+- [ ] No existing tool components modified (unless bug fix)
+- [ ] All tests pass (`vitest run` + `pytest`)
+- [ ] Build succeeds (`npx vite build`)
+- [ ] New routes added to `routes.ts` registry
+- [ ] New i18n keys added to all 3 language files (en, ar, fr)
+- [ ] Feature flag added if the feature can be disabled
+
+### File Structure Convention
+
+```
+frontend/src/
+├── components/
+│   ├── layout/         # Header, Footer, AdSlot
+│   ├── shared/         # Reusable components (ToolCard, ErrorBoundary)
+│   ├── seo/            # SEOHead, ToolLandingPage, FAQSection
+│   └── tools/          # One file per tool (PdfToWord.tsx, etc.)
+├── config/
+│   ├── routes.ts       # Canonical route registry (NEVER delete entries)
+│   ├── featureFlags.ts # Frontend feature flag reader
+│   ├── seoData.ts      # SEO metadata for all tools
+│   └── toolLimits.ts   # File size limits
+├── hooks/              # Custom React hooks
+├── i18n/               # Translation files (en.json, ar.json, fr.json)
+├── pages/              # Page components (HomePage, AboutPage, etc.)
+├── services/           # API clients, analytics
+├── stores/             # Zustand stores
+└── utils/              # Pure utility functions (seo.ts, etc.)
+```