| 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.
