[ML integration] Generate a versioned API client and establish database schema ownership
- Dominant language
- TypeScript
- Stars
- 4
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
The backend currently models recommendation batches as `unknown[]` and feed items as `any`, so incompatible ML changes are accepted at compile time:
- https://github.com/ACM-VIT/gh-social/blob/49073fc71423aa8e10334158d70ac6d41be1dbc0/backend/services/mlService.ts#L5-L37
- https://github.com/ACM-VIT/gh-social/blob/49073fc71423aa8e10334158d70ac6d41be1dbc0/backend/services/feedService.ts#L36-L77
Both repositories also create or alter the shared `repo` schema independently. The Drizzle schema, SQL migrations, and Python runtime DDL already disagree about fields such as `primary_language` and `open_issues_count`.
The backend still exposes an internal recommendation callback even though the current ML request returns recommendation batches synchronously:
- https://github.com/ACM-VIT/gh-social/blob/49073fc71423aa8e10334158d70ac6d41be1dbc0/backend/controllers/feedController.ts#L1-L20
## Proposed change
- Publish a versioned OpenAPI contract from the ML service.
- Generate the TypeScript request/response client used by the backend.
- Include a schema/API version and model provenance in recommendation responses.
- Make `gh-social` migrations the single owner of application database tables.
- Treat ML as a consumer of those tables or give it a separate feature-store schema.
- Remove runtime table creation/alteration from ML production paths.
- Remove or document the legacy callback endpoint.
## Acceptance criteria
- No `any` or `unknown[]` remains at the ML integration boundary.
- Contract generation runs in CI and detects incompatible changes.
- Exactly one repository owns migrations for each shared table.
- ML startup performs compatibility checks but does not mutate app schema.
- Recommendation responses contain stable typed IDs, source, scores, and model/embedding versions.
- A cross-repo integration test exercises onboard, embed, recommend, impression, and feedback flows.
Contributor guide
Research direction
Start with backend/services/mlService.ts, backend/services/feedService.ts, and backend/controllers/feedController.ts, then compare the Drizzle schema, SQL migrations, and Python runtime DDL referenced in the issue. Trace the current ML request and database startup paths before defining the contract and ownership boundaries. Done means the listed acceptance criteria hold, including generated-client checks and a cross-repo integration test.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python, sql, typescript
- Domain
- api, backend, ci-cd, databases, machine-learning, testing-qa
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100