Conversational Development With Claude Code — Part 13: Integrating Ratings with the API (Full‑Stack Alignment)

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:

http://localhost:8000/docs

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:

1. Identify the endpoint that returns ratings per course.


2. Confirm response structure via OpenAPI.


3. Map backend response to TypeScript interface.


4. Replace mock rating in the component.


5. Ensure asynchronous data handling is stable.


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

1. Modified backend to include rating aggregation in course list response.


2. Updated response schema.


3. Regenerated OpenAPI documentation.


4. 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 average and totalReviews
  


• 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:

1. Endpoint for saving student rating.


2. Frontend submission handler.


3. Personal rating visualization in course detail.


4. State update after submission.


5. Optimistic update strategy (optional).


6. 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 adddir for 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