Flask API Development

Overview

The Chuuk Dictionary backend is a single-file monolith: app.py (~4150 lines) that contains all routes, auth logic, translation pipelines, OCR helpers, and database access. There is no Blueprint split.

Application Structure

chuuk/ ├── app.py # All Flask routes and logic (~4150 lines) ├── src/ │ ├── core/jworg_lookup.py # JW.org word lookup │ ├── database/ │ │ ├── db_factory.py # Connection helpers (module-level functions) │ │ └── dictionary_db.py # DictionaryDB class │ ├── ocr/ocr_processor.py │ ├── translation/ │ │ ├── helsinki_translator_v2.py │ │ └── hybrid_translator.py │ └── utils/nwt_epub_parser.py ├── config/ │ ├── users.json # Authorised users │ └── bible_books.json # Bible book metadata (66 books) └── requirements.txt

Key Conventions

Module-level globals (not injected)

app.py — initialised at startup (not inside routes)

dict_db = DictionaryDB() # database handle — NOT app.db training_status = {} # background job state training_status_lock = threading.Lock() # guards training_status mutations

helsinki_translator = None # loaded lazily via load_helsinki_translator()

CORS is disabled (flask_cors import is commented out). Add it back deliberately if needed.

Magic-link authentication (no passwords)

magic_links = {} # {token: {'email': email, 'expires': datetime}} active_sessions = {} # {email: session_id} — enforces single active session

@app.route('/api/auth/request-magic-link', methods=['POST']) def request_magic_link(): email = request.json.get('email', '').lower().strip() # ... validate email against users.json, generate token, send SMTP email ...

@app.route('/auth/magic/<token>') def magic_link_login(token): # ... validate token, create session, redirect to frontend ...

Route return pattern

@app.route('/api/dictionary/search', methods=['GET']) @login_required def api_search(): try: query = request.args.get('q', '') results = dict_db.search_entries(query) # use dict_db, not app.db return jsonify({'results': results}) except Exception as e: app.logger.error(f'Search error: {e}') return jsonify({'error': str(e)}), 500

Background training jobs

Mutate training_status only inside training_status_lock :

with training_status_lock: training_status['state'] = 'running'

Bible data

Loaded from config/bible_books.json — do NOT hardcode inline

BIBLE_BOOKS = _load_bible_books() # dict keyed by book name

Environment Variables

Variable Purpose Default

FLASK_SECRET_KEY

Session signing key random (dev) / required (prod)

FLASK_ENV

Environment tag —

COSMOS_DB_CONNECTION_STRING

Cosmos DB URI —

SMTP_HOST/PORT/USER/PASSWORD

Magic-link email stdout fallback

GOOGLE_VISION_API_KEY

Cloud Vision OCR optional

Testing

See tests/conftest.py . Mock dict_db via patch('app.dict_db', mock_db) .

Source Files

• Backend entry point: app.py

• Database layer: src/database/dictionary_db.py

• Auth logic: app.py (magic-link sections, ~line 83–170)