# eldarnr/rick-and-morty architecture

> Architecture diagram of the GitHub repository eldarnr/rick-and-morty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eldarnr/rick-and-morty
- Repository: https://github.com/eldarnr/rick-and-morty

## Overview

#### Purpose and runtime entry points
Rick and Morty Explorer is a two-tier application for searching, filtering, and viewing character profiles, with AI-generated character commentary. The React/Vite browser client starts at `frontend/src/main.tsx` and is composed from `frontend/src/App.tsx`. The Python FastAPI service is exposed through `backend/app/main.py`, typically run as `uvicorn app.main:app`.

#### Frontend application shell and navigation
The client uses React 18, TypeScript, and React Router to present list and detail views. Route definition is centralized in `frontend/src/router.tsx`; shared navigation/page framing is in `frontend/src/layout/Layout.tsx` and `frontend/src/layout/Navbar.tsx`. This boundary keeps route-level data/UI behavior separate from persistent layout.

#### Character discovery flow
The character browser is implemented by `frontend/src/pages/CharacterList.tsx`, with reusable result rendering and pagination in `frontend/src/components/CharacterCard.tsx` and `frontend/src/components/Pagination.tsx`. User name/status filters and page changes drive requests through the frontend API layer, then render cards or skeleton states while data is pending.

#### Character detail and AI insight flow
Selecting a card navigates to the profile view in `frontend/src/pages/CharacterDetail.tsx`. It displays richer character attributes—such as origin, location, and episode data—and requests the backend’s AI-backed description capability. `frontend/src/components/CharacterDetailSkeleton.tsx` represents the detail loading boundary.

#### Frontend-to-backend API boundary
`frontend/src/api/client.ts` is the client-side integration boundary for backend HTTP calls. Domain response shapes are represented in `frontend/src/types/index.ts`, allowing pages/components to consume typed character data rather than embed transport details. The frontend should not directly depend on the official Rick and Morty API; the FastAPI service is the proxy/facade.

#### Backend API and service stages
FastAPI initialization/configuration occurs in `backend/app/main.py` and `backend/app/config.py`; HTTP endpoints are defined in `backend/app/routers.py`. Route handlers delegate external API retrieval and Gemini generation to `backend/app/services.py`. This separates request/response concerns from asynchronous outbound HTTP and AI business logic.

#### External services and deployment
The backend asynchronously wraps the official Rick and Morty API via HTTPX and calls Google Gemini Pro using a `GEMINI_API_KEY` environment value. Expected local endpoints are frontend Vite on port 5173 and FastAPI on port 8000. Deployment intent is a static/frontend deployment such as Vercel (`frontend/vercel.json`) paired with a separately hosted Python backend, e.g. Render.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/api/client.ts) (Frontend API client), [`frontend/src/App.tsx`](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/App.tsx) (App shell), [`frontend/src/router.tsx`](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/router.tsx) (Route definitions), [`frontend/src/pages/CharacterList.tsx`](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/pages/CharacterList.tsx) (Character discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_frontend_entry["Vite entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app_shell["App shell<br/>React composition<br/>[App.tsx]"]
  node_router["Route definitions<br/>React Router<br/>[router.tsx]"]
  node_layout["Shared layout<br/>page frame<br/>[Layout.tsx]"]
  node_navbar["Navigation bar<br/>navigation UI<br/>[Navbar.tsx]"]
  node_character_list["Character discovery<br/>list page<br/>[CharacterList.tsx]"]
  node_list_components["Cards and pagination<br/>reusable UI<br/>[CharacterCard.tsx]"]
  node_character_detail["Character profile<br/>detail page"]
  node_detail_skeleton["Detail loading state<br/>loading UI"]
  node_frontend_api["Frontend API client<br/>HTTP integration<br/>[client.ts]"]
  node_types["Character types<br/>TypeScript models<br/>[index.ts]"]
end

subgraph group_backend["FastAPI backend"]
  node_fastapi_app["FastAPI application<br/>service entry<br/>[main.py]"]
  node_backend_config["Backend configuration<br/>service config<br/>[config.py]"]
  node_routers["HTTP endpoints<br/>FastAPI routers<br/>[routers.py]"]
  node_services["Character and AI service<br/>async service layer<br/>[services.py]"]
end

subgraph group_external["External services"]
  node_rick_morty_api{{"Rick and Morty API<br/>external character API"}}
  node_gemini{{"Google Gemini Pro<br/>AI generation API"}}
end

node_browser(("Browser user<br/>user agent"))

node_browser -->|"loads"| node_frontend_entry
node_frontend_entry -->|"mounts"| node_app_shell
node_app_shell -->|"uses"| node_router
node_app_shell -->|"wraps routes"| node_layout
node_layout -->|"renders"| node_navbar
node_router -->|"list route"| node_character_list
node_router -->|"profile route"| node_character_detail
node_character_list -->|"renders"| node_list_components
node_character_list -->|"filters and pages"| node_frontend_api
node_character_detail -.->|"while loading"| node_detail_skeleton
node_character_detail -->|"character and insight"| node_frontend_api
node_frontend_api -->|"uses response models"| node_types
node_frontend_api -->|"HTTP requests"| node_fastapi_app
node_fastapi_app -->|"loads"| node_backend_config
node_fastapi_app -->|"registers"| node_routers
node_routers -->|"delegates"| node_services
node_services -->|"async HTTPX retrieval"| node_rick_morty_api
node_services -->|"generates commentary"| node_gemini

click node_frontend_entry "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/main.tsx"
click node_app_shell "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/App.tsx"
click node_router "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/router.tsx"
click node_layout "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/layout/Layout.tsx"
click node_navbar "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/layout/Navbar.tsx"
click node_character_list "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/pages/CharacterList.tsx"
click node_list_components "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/components/CharacterCard.tsx"
click node_character_detail "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/pages/CharacterDetail.tsx"
click node_detail_skeleton "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/components/CharacterDetailSkeleton.tsx"
click node_frontend_api "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/api/client.ts"
click node_types "https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/types/index.ts"
click node_fastapi_app "https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/config.py"
click node_routers "https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/routers.py"
click node_services "https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/services.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_entry,node_app_shell,node_router,node_layout,node_navbar,node_character_list,node_list_components,node_character_detail,node_detail_skeleton,node_frontend_api,node_types toneBlue
class node_fastapi_app,node_backend_config,node_routers,node_services toneAmber
class node_rick_morty_api,node_gemini toneMint
class node_browser toneNeutral
```

## Components

### React frontend

Browser client on Vite.

- [Vite entry](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/main.tsx): React bootstrap · `frontend/src/main.tsx`
- [App shell](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/App.tsx): React composition · `frontend/src/App.tsx`
- [Route definitions](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/router.tsx): React Router · Selects list and detail views. · `frontend/src/router.tsx`
- [Shared layout](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/layout/Layout.tsx): page frame · Persistent navigation and framing. · `frontend/src/layout/Layout.tsx`
- [Navigation bar](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/layout/Navbar.tsx): navigation UI · `frontend/src/layout/Navbar.tsx`
- [Character discovery](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/pages/CharacterList.tsx): list page · Filters, paginates, and renders search results. · `frontend/src/pages/CharacterList.tsx`
- [Cards and pagination](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/components/CharacterCard.tsx): reusable UI · Character result rendering and page controls. · `frontend/src/components/CharacterCard.tsx`
- [Character profile](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/pages/CharacterDetail.tsx): detail page · Shows attributes and requests AI commentary. · `frontend/src/pages/CharacterDetail.tsx`
- [Detail loading state](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/components/CharacterDetailSkeleton.tsx): loading UI · `frontend/src/components/CharacterDetailSkeleton.tsx`
- [Frontend API client](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/api/client.ts): HTTP integration · Typed boundary for backend calls. · `frontend/src/api/client.ts`
- [Character types](https://github.com/eldarnr/rick-and-morty/blob/main/frontend/src/types/index.ts): TypeScript models · `frontend/src/types/index.ts`

### FastAPI backend

HTTP facade and AI orchestration.

- [FastAPI application](https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/main.py): service entry · Runs on port 8000. · `backend/app/main.py`
- [Backend configuration](https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/config.py): service config · Provides Gemini API-key configuration. · `backend/app/config.py`
- [HTTP endpoints](https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/routers.py): FastAPI routers · Maps frontend requests to service operations. · `backend/app/routers.py`
- [Character and AI service](https://github.com/eldarnr/rick-and-morty/blob/main/backend/app/services.py): async service layer · Retrieves character data and generates commentary. · `backend/app/services.py`

### External services

- **Rick and Morty API**: external character API · Accessed only by the backend via HTTPX.
- **Google Gemini Pro**: AI generation API · Uses GEMINI_API_KEY.

### Other components

- **Browser user**: user agent

## Connections

- Browser user → Vite entry: loads
- Vite entry → App shell: mounts
- App shell → Route definitions: uses
- App shell → Shared layout: wraps routes
- Shared layout → Navigation bar: renders
- Route definitions → Character discovery: list route
- Route definitions → Character profile: profile route
- Character discovery → Cards and pagination: renders
- Character discovery → Frontend API client: filters and pages
- Character profile → Detail loading state: while loading
- Character profile → Frontend API client: character and insight
- Frontend API client → Character types: uses response models
- Frontend API client → FastAPI application: HTTP requests
- FastAPI application → Backend configuration: loads
- FastAPI application → HTTP endpoints: registers
- HTTP endpoints → Character and AI service: delegates
- Character and AI service → Rick and Morty API: async HTTPX retrieval
- Character and AI service → Google Gemini Pro: generates commentary