Conversational Development With Claude Code — Part 13: Integrating Ratings with the API (Full‑Stack Alignment)
TL;DR
In this chapter we complete the ratings system by integrating the frontend star‑rating UI with the real backend API. Using Claude Code, Swagger, openapi.json, multi-directory context (adddir), and coordinated backend adjustments, we move from mock data to real, production-ready data flowing end‑to‑end.
This is where the system stops being layered — and starts being unified.
When abstraction meets reality
Until now, the ratings feature existed in carefully isolated layers:
- Database schema ✔
- Backend services and endpoints ✔
- Frontend star UI with mock data ✔
But isolation is a phase — not a destination.
Part 13 is about alignment.
The moment where:
- The frontend stops pretending.
- The backend stops being invisible.
- And data flows across the boundary in a controlled, documented, verifiable way.
This is full-stack maturity.
The prerequisite: production-oriented schema
The integration starts from strength.
We already have:
- A normalized ratings table per course
- Validated service-layer logic
- Endpoints exposed via FastAPI
- Swagger documentation available
- Real data in PostgreSQL
The integration is not guesswork.
It is orchestration.
Multi-directory context: thinking across repositories
Frontend and backend live in separate directories.
Claude Code can reason across both — but only if we give it visibility.
Inside backend:
pwd
Copy the absolute path.
Inside Claude Code:
adddir /absolute/path/to/backend
Now the assistant sees:
- Backend models
- Endpoints
- Database schema
- Frontend components
- TypeScript types
This is not convenience.
This is cognitive unification across projects.
Multi-repo context is a professional skill.
Reading the API properly: Swagger + OpenAPI
Before writing a single integration line, we validate the contract.
Navigate to:
Swagger exposes:
- All endpoints
- Parameters
- Response schemas
- Validation rules
Click the link to:
/openapi.json
This file is gold.
It is machine-readable truth.
You can:
- Copy the JSON and provide it as context
- Or let Claude Code fetch it directly:
curl http://localhost:8000/openapi.json
The assistant can now:
- Infer routes
- Detect response types
- Identify missing fields
- Validate schema mismatches
No assumptions.
Only contracts.
Replacing mock data with real API calls
With context unified, the instruction becomes surgical:
Integrate the ratings endpoint into the course list component. Replace mock values with real API data.
Steps executed:
- Identify the endpoint that returns ratings per course.
- Confirm response structure via OpenAPI.
- Map backend response to TypeScript interface.
- Replace mock rating in the component.
- Ensure asynchronous data handling is stable.
- Validate rendering states.
The frontend now consumes reality.
The discovery moment: rating missing in course list
Integration exposes truth.
Claude Code detected:
The course list endpoint did not include rating information.
This is where senior engineering differs from superficial integration.
Instead of hacking around it, we:
- Modified backend to include rating aggregation in course list response.
- Updated response schema.
- Regenerated OpenAPI documentation.
- Adjusted frontend mapping accordingly.
Integration is bidirectional refinement.
Backend adjustment for list endpoint
The backend change required:
- Extending the course query
- Joining aggregated rating values
- Returning:
- average rating
- total ratings count
- Updating Pydantic response model
Now the list endpoint is complete.
Swagger reflects the change.
Contracts are synchronized.
Frontend mapping discipline
On the frontend, we:
- Updated the TypeScript interface
- Replaced mock
averageandtotalReviews - Connected to real API call
- Handled loading state
- Handled empty rating state
- Preserved UI balance
No silent assumptions.
Every property is typed.
Real browser validation
After integration, verification happens in the browser.
Observed results:
- React course → 4 ratings, average 4.25 → then 4.5 (after update)
- Python course → 2 ratings
- Consistency between list and detail view
Verification checklist:
- Does total match database?
- Does average calculation match backend?
- Does UI update correctly?
- Are edge cases handled?
If the browser lies, the system is incomplete.
The hidden skill: contract literacy
The most important skill exercised here was not writing code.
It was reading contracts.
- Swagger interpretation
- Schema mapping
- Response validation
- Error case analysis
- Coordinated backend/frontend change
Claude Code accelerates execution.
But clarity of contract determines correctness.
The final integration state
By the end of Part 13, we achieved:
- Real API consumption in frontend
- Coordinated backend update
- Accurate aggregation rendering
- Verified browser consistency
- Swagger-aligned documentation
- End-to-end functional ratings system
This is not feature completion.
This is architectural convergence.
The final challenge for students
To move from display to interaction, implement:
- Endpoint for saving student rating.
- Frontend submission handler.
- Personal rating visualization in course detail.
- State update after submission.
- Optimistic update strategy (optional).
- Proper authorization validation.
Now the system becomes participatory.
What this chapter truly represents
Integration is not a technical step.
It is a philosophical one.
Frontend and backend are not separate disciplines.
They are two perspectives on the same truth.
Claude Code becomes powerful when it understands both.
And you become senior when you do too.
If you completed this integration:
- Did you use
adddirfor multi-repo reasoning? - Did you validate via Swagger?
- Did you adjust backend instead of hacking frontend?
- Did you verify in the browser with real data?
Share your experience in the comments.
Next chapter: personal ratings, optimistic UI, and production-hardening.
— Cristian Sifuentes
Full-stack engineer · AI-assisted systems thinker
Top comments (0)