chromestatus-backend

name	chromestatus-backend
description	Guidance for working on the Flask-based backend, NDB Datastore, and OpenAPI integrations in chromium-dashboard.

Backend Development Skill

This skill provides context and guidelines for developing the backend of the chromium-dashboard project.

Core Technologies

• Flask: The primary web framework for request handling and template rendering.
• Cloud NDB: Used for interacting with Google Cloud Datastore.
• OpenAPI 3.0: Used for defining APIs and generating Python data models.

Key Directories

• api/: Contains Flask request handlers for various API endpoints.
• framework/: Core infrastructure, including basehandlers.py and utility functions.
• internals/: Business logic, search filters, and data processing.
• pages/: (LEGACY) Handlers for main application pages. Do not add new code here.
• openapi/: OpenAPI specification file (api.yaml).
• gen/py/chromestatus_openapi/: Auto-generated Python models from OpenAPI.

Guidelines

• API Development: Prefer adding new APIs via OpenAPI in openapi/api.yaml. Use make openapi to regenerate models.

  [!IMPORTANT] Targeted OpenAPI Post-Generation Fix: openapi-generator-cli overwrites custom TypeScript 6 configurations in gen/js/chromestatus-openapi (package.json, tsconfig.json, tsconfig.esm.json) and downgrades "typescript" to "^4.0 || ^5.0" under "gen/js/chromestatus-openapi" in package-lock.json. Immediately after running make openapi, ensure "typescript": "^6.0" is restored under "gen/js/chromestatus-openapi" in package-lock.json and the 3 gen/js/chromestatus-openapi config files are kept on origin/main baseline.

• Handlers: Extend basehandlers.py classes for consistent permission checking and response handling. Do not add new handlers to the legacy pages/ directory.
• Datastore: Use NDB models defined in internals/models.py. Ensure queries are optimized and use proper indexing (see index.yaml).
• Testing: Python unit tests are located alongside the code (e.g., *_test.py). Run them using npm test.

Common Tasks

• Adding a Route: Define the route in @main.py and map it to a handler class in api/ or pages/.
• Modifying Schema: Update @internals/models.py and run a backfill script if necessary.