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, includingbasehandlers.pyand 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. Usemake openapito regenerate models.[!IMPORTANT] Targeted OpenAPI Post-Generation Fix:
openapi-generator-clioverwrites custom TypeScript 6 configurations ingen/js/chromestatus-openapi(package.json,tsconfig.json,tsconfig.esm.json) and downgrades"typescript"to"^4.0 || ^5.0"under"gen/js/chromestatus-openapi"inpackage-lock.json. Immediately after runningmake openapi, ensure"typescript": "^6.0"is restored under"gen/js/chromestatus-openapi"inpackage-lock.jsonand the 3gen/js/chromestatus-openapiconfig files are kept onorigin/mainbaseline. - Handlers: Extend
basehandlers.pyclasses for consistent permission checking and response handling. Do not add new handlers to the legacypages/directory. - Datastore: Use NDB models defined in
internals/models.py. Ensure queries are optimized and use proper indexing (seeindex.yaml). - Testing: Python unit tests are located alongside the code (e.g.,
*_test.py). Run them usingnpm test.
Common Tasks
- Adding a Route: Define the route in @main.py and map it to a handler class in
api/orpages/. - Modifying Schema: Update @internals/models.py and run a backfill script if necessary.