Pokémon API Project — System Reference

Overview

This project is a full-stack Pokémon data application consisting of:

• A Python backend API (FastAPI) that fetches, normalizes, and validates Pokémon data from external sources
• A React frontend that queries the backend and renders a consistent Pokémon card UI
• A clearly defined data contract (PokemonCard) shared implicitly between backend and frontend

The project emphasizes clear data modeling, strict contracts, and debuggable system flow over feature breadth.

---

Architecture Summary

Frontend (React)
↓ HTTP (fetch)
Backend API (FastAPI)
↓ Service Layer
External Pokémon APIs

• Frontend is stateless beyond UI state
• Backend owns data normalization and validation
• External APIs are treated as untrusted inputs

---

Data Canon (Authoritative)

Core Data Model (models.py)

PokemonCard

The canonical data structure for the entire application.

Field	Type	Notes
id	int	Pokémon ID
name	str	Pokémon name
types	List[str]	Flattened strings, not nested objects
sprites	SpriteUrls	Image URLs
evolution	EvolutionInfo	Evolution chain metadata

SpriteUrls

Field	Type
default	str | None
official	str | None

EvolutionInfo

Field	Description
root	First Pokémon in the evolution chain
stages	Linear list of evolution names
current_index	Index of the current Pokémon in stages

---

API Standards

Base URLs

• Production: https://pokemon-backend-wvbb.onrender.com
• Local: http://127.0.0.1:8000

Route Prefix

All data routes must start with:

Error Codes

Code	Meaning
404	Pokémon not found (user error)
500	Internal server error (code error)

---

Legacy Code Notice

• PokemonSearch.jsx is deprecated
• Active search logic lives in App.jsx
• Do not add new features to PokemonSearch.jsx

---

System Trace (Lifecycle Reference)

Use this section when debugging behavior, tracing failures, or onboarding.

Phase 1 — Frontend Trigger

1. User submits a Pokémon name in App.jsx
2. UI state changes to "loading"
3. fetchPokemon(name) is called
   • Builds URL using API_BASE
   • Sends a GET request

---

Phase 2 — Backend Entry

4. main.py receives the request
   • CORS middleware validates origin
5. api.py routes /pokemon/{name}
   • Delegates to pokemon_service.get_pokemon_card()

---

Phase 3 — Service Logic

6. pokemon_service.py orchestrates data retrieval

   • Fetch Pokémon stats
   • Fetch species data

7. Evolution resolution

   • Fetches evolution-chain URL
   • Runs DFS over evolves_to
   • Produces a linear evolution path
   • Determines current_index

---

Phase 4 — Validation & Response

8. Data normalization

   • Flattens nested API responses

9. Contract enforcement

   • Packs data into PokemonCard
   • Applies defaults via Pydantic

10. Response

• 200 OK on success
• 404 if Pokémon not found

---

Phase 5 — Frontend Render

11. Frontend receives JSON

12. PokemonCard.jsx renders:

• Image fallback: Official → Default → Placeholder
• Evolution chain rendered as a → b → c

---

Design Principles

• Backend normalizes, frontend renders
• External APIs are untrusted
• Data contracts are explicit
• Errors are translated at boundaries
• UI reflects async state explicitly

---

Status

This project is feature-frozen.

Future work should:

• Respect existing data contracts
• Preserve system trace assumptions
• Avoid modifying legacy components unless refactoring intentionally

---