flask-sync 🔗

Automatically detect field mismatches between your Flask API and frontend JS. No more undefined debugging.

---

The problem

// Flask returns user_id, you wrote userId
console.log(res.userId)      // undefined ❌
console.log(res.user_name)   // undefined ❌  backend uses username
console.log(res.token)       // correct ✅

You spend 30 minutes debugging, only to find it was just a field name mismatch.

flask-sync finds all of these in one command.

---

Demo

$ python3 cli.py diff app.py frontend.js

📌 POST /api/login
   ✅ token
   ✅ username
   ⚠️  userId        (backend doesn't have this  →  did you mean 'user_id'?)
   ⚠️  user_name     (backend doesn't have this)
   💡 user_id        (backend returns this, but frontend never uses it)

📌 GET /api/users/<user_id>
   ✅ email
   ✅ username
   ⚠️  createdAt     (backend doesn't have this  →  did you mean 'created_at'?)
   💡 created_at     (backend returns this, but frontend never uses it)

⚠️  Field mismatches found, check the report above

---

Install

git clone https://github.com/kyawmt2000/flask-sync
cd flask-sync
pip3 install click

No API keys required. Runs fully offline.

---

Usage

Detect field mismatches (most useful)

python3 cli.py diff your_app.py your_frontend.js

Preview all routes

python3 cli.py preview your_app.py

Generate frontend API docs

python3 cli.py scan your_app.py
# outputs api_docs.js and api.json

Custom output paths

python3 cli.py scan your_app.py --output docs/api.js --json-output docs/api.json

---

How it works

Pure AST static analysis — no AI, no network calls, no API keys:

1. Scans your Flask file for all @app.route decorators
2. Extracts field names from jsonify({...}) return values
3. Scans your frontend JS for all res.xxx / data.xxx field references
4. Compares both sides and reports mismatches
5. Auto-suggests similar fields (camelCase vs snake_case)

Runs locally in milliseconds.

---

Supported patterns

Backend (auto-detected):

return jsonify({"user_id": 1, "username": "tom"})
return {"token": "xxx", "expires": 3600}

Frontend (auto-detected):

res.user_id / data.username / response.token
res['field_name']

---

Output example

api_docs.js:

/**
 * User login
 *
 * @route POST /api/login
 *
 * @param {*} body.email - user email
 * @param {*} body.password - login password
 * @returns {{ token: string, user_id: number, username: string }}
 */

---

Project structure

flask_sync/
├── scanner.py      # AST scanning for Flask routes
├── analyzer.py     # field extraction from route functions
├── generator.py    # JSDoc + OpenAPI generation
├── diff.py         # frontend/backend field comparison
cli.py              # CLI entry point
sample_app.py       # sample Flask app for testing
sample_frontend.js  # sample frontend JS for testing

---

Roadmap

• Flask route scanning
• AST field extraction
• Frontend/backend diff detection
• camelCase / snake_case smart suggestions
• Watch mode (auto re-run on file change)
• VS Code extension
• Django REST Framework support
• TypeScript frontend support

---

Contributing

PRs and issues welcome, especially:

• More frontend field access patterns
• More Flask return value patterns
• Bug reports

---

License

MIT