# kotkoa/rickandmorty architecture

> Architecture diagram of the GitHub repository kotkoa/rickandmorty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kotkoa/rickandmorty
- Repository: https://github.com/kotkoa/rickandmorty

## Overview

##### Project type and purpose
- This is a single-page, client-side web application (built with Vite + React + TypeScript) that lets users browse “Rick and Morty” characters, locations, and episodes.
- It acts purely as a frontend; it queries the public Rick and Morty GraphQL API via Apollo Client and manages UI state with Jotai.

##### File structure
- Top-level config: .env(.example), codegen.yml, tsconfig.json, vite.config.mts, ESLint/Prettier configs.
- src/ contains:
- apolloClient/ – Apollo Client setup pointing at the external GraphQL endpoint
- components/ – UI components organized by feature (char-card, char-list, details, pagination, etc.)
- routes/ – app-router.tsx defines React Router routes or equivalent
- store/ – Jotai atoms for global state (e.g., characters.store.ts)
- queries/ – .gql query definitions
- generated/ – GraphQL codegen output (graphql.tsx, types)
- src/main.tsx & src/root.tsx bootstrap the React application.
- Tests live under src/__tests__, exercising components with React Testing Library.

##### README
- Confirms tech stack: Vite, React, TypeScript, Apollo GraphQL, Jotai, React Testing Library.
- No backend or microservices—all GraphQL data comes from the public API.

a. Main components:
- Client (Browser) running the bundled React SPA
- Vite Dev/Build Toolchain (serves during dev & bundles for prod)
- React Application Layers:
– Presentation/UI Layer (components folder)
– Routing Layer (app-router.tsx in routes/)
– State Management Layer (Jotai atoms in store/)
– Data Layer (Apollo Client in apolloClient/)
- GraphQL Code Generation (codegen.yml → generated/graphql.tsx)
- External Service: Rick and Morty GraphQL API
- Developer Tooling: ESLint, Prettier, TypeScript config (for build and lint pipelines)
- Test Runner (React Testing Library in __tests__)

b. Relationships and interactions:
1. Browser requests index.html → Vite serves the SPA.
2. main.tsx/root.tsx initialize React, wrap in ApolloProvider and Jotai Provider.
3. UI Components subscribe to Jotai atoms or directly invoke GraphQL queries via Apollo hooks.
4. Queries defined in queries/*.gql and code-generated types in generated/ ensure type safety.
5. Apollo Client sends HTTP requests to the Rick and Morty GraphQL endpoint, receives JSON responses.
6. State updates flow back into the React component tree.
7. CSS Modules (component-scoped .module.scss) style individual components; global CSS for reset and fonts.
8. Tests simulate user interactions against mounted components, verifying behavior.

c. Architectural patterns / design principles:
- Component-based UI (atomic & feature-oriented organization)
- Unidirectional data flow (React → Jotai/Apollo → External API)
- Separation of concerns: UI vs. state vs. data fetching vs. styling
- Type-safe GraphQL integration via codegen

d. Relevant technologies:
- Vite (dev server, bundler)
- React + React Router (component & navigation)
- TypeScript (static typing)
- Apollo Client (GraphQL data fetching)
- graphql-codegen (type/s API stubs generator)
- Jotai (minimal global state)
- SCSS Modules & CSS (styles)
- ESLint/Prettier (code quality)
- React Testing Library + Jest (tests)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Tooling
    subgraph "Build & Tooling"
        direction TB
        Env[".env / .env.example"]:::tooling
        TSConfig["tsconfig.json"]:::tooling
        ViteConfig["vite.config.mts"]:::tooling
        ESLint[".eslintrc.js / .eslintignore"]:::tooling
        Prettier[".prettierrc.js / .prettierignore"]:::tooling
        Stylelint["stylelint.config.js"]:::tooling
        CodegenConfig["codegen.yml"]:::tooling
    end

    %% GraphQL Code Generation
    subgraph "GraphQL Codegen"
        direction TB
        Queries["Query Definitions\n(queries.gql)"]:::data
        GenHooks["Generated Types & Hooks\n(graphql.tsx)"]:::data
        GenTypes["Generated Type Definitions\n(graphql.d.ts)"]:::data
    end

    %% Bootstrap
    subgraph "Application Bootstrap"
        direction TB
        Main["Entry Point\n(main.tsx)"]:::tooling
        Root["Root & Providers\n(root.tsx)"]:::tooling
    end

    %% Data Layer
    subgraph "Data Access Layer"
        direction TB
        ApolloClient["Apollo Client Setup\n(apollo-client.ts)"]:::data
    end

    %% State Layer
    subgraph "State Management Layer"
        direction TB
        JotaiStore["Jotai Atoms\n(characters.store.ts)"]:::state
    end

    %% Routing Layer
    subgraph "Routing Layer"
        direction TB
        Router["App Router\n(app-router.tsx)"]:::state
    end

    %% UI Components
    subgraph "Presentation/UI Layer"
        direction TB
        CharCard["Character Card"]:::ui
        CharList["Character List"]:::ui
        DetailsPage["Details Page"]:::ui
        Pagination["Pagination"]:::ui
        Header["Header"]:::ui
        Footer["Footer"]:::ui
        ErrorFallback["Error Fallback"]:::ui
        Welcome["Welcome Screen"]:::ui
        Favorites["Favorites List"]:::ui
        Interesting["Interesting Characters"]:::ui
    end

    %% Assets & Styles
    subgraph "Assets & Styles"
        direction TB
        Fonts["Fonts\n(src/assets/fonts)"]:::asset
        Icons["Icons Components\n(src/icons)"]:::asset
        GlobalCSS["Global Styles\n(index.css, App.css,\nfonts.css)"]:::asset
    end

    %% Testing
    subgraph "Testing"
        direction TB
        Tests["React Testing Library\n(App.test.tsx)"]:::tooling
    end

    %% External Service
    RickMortyAPI["Rick & Morty GraphQL API"]:::external

    %% Connections
    Env --> ViteConfig
    ViteConfig --> Main
    Main --> Root
    Root --> ApolloClient
    Root --> JotaiStore
    Root --> Router

    ApolloClient --> RickMortyAPI
    Queries --> GenHooks
    GenHooks --> ApolloClient

    Router --> CharList
    Router --> DetailsPage
    Router --> Welcome
    Router --> Favorites
    Router --> Interesting

    CharList --> CharCard
    CharList --> Pagination
    DetailsPage --> CharCard

    CharCard --> ErrorFallback

    CharList --> JotaiStore
    DetailsPage --> JotaiStore
    Favorites --> JotaiStore
    Interesting --> JotaiStore

    CharList --> ApolloClient
    DetailsPage --> ApolloClient
    Favorites --> ApolloClient

    Fonts --> GlobalCSS
    Icons --> GlobalCSS
    GlobalCSS --> CharCard
    GlobalCSS --> CharList
    GlobalCSS --> DetailsPage

    Tests --> CharCard
    Tests --> CharList
    Tests --> DetailsPage
    Tests --> ApolloClient

    %% Click Events
    click CharCard "https://github.com/kotkoa/rickandmorty/blob/master/src/components/char-card/char-card.tsx"
    click CharCard "https://github.com/kotkoa/rickandmorty/blob/master/src/components/char-card/char-card.module.scss"
    click CharList "https://github.com/kotkoa/rickandmorty/blob/master/src/components/char-list/char-list.tsx"
    click CharList "https://github.com/kotkoa/rickandmorty/blob/master/src/components/char-list/char-list.module.scss"
    click DetailsPage "https://github.com/kotkoa/rickandmorty/blob/master/src/components/details/details.tsx"
    click DetailsPage "https://github.com/kotkoa/rickandmorty/blob/master/src/components/details/details.module.scss"
    click Pagination "https://github.com/kotkoa/rickandmorty/blob/master/src/components/pagination/pagination.tsx"
    click Pagination "https://github.com/kotkoa/rickandmorty/blob/master/src/components/pagination/pagination.module.scss"
    click Header "https://github.com/kotkoa/rickandmorty/blob/master/src/components/header/header.tsx"
    click Header "https://github.com/kotkoa/rickandmorty/blob/master/src/components/header/header.module.scss"
    click Footer "https://github.com/kotkoa/rickandmorty/blob/master/src/components/footer/footer.tsx"
    click Footer "https://github.com/kotkoa/rickandmorty/blob/master/src/components/footer/footer.module.scss"
    click ErrorFallback "https://github.com/kotkoa/rickandmorty/blob/master/src/components/oh-no/oh-no.tsx"
    click ErrorFallback "https://github.com/kotkoa/rickandmorty/blob/master/src/components/oh-no/oh-no.module.scss"
    click Welcome "https://github.com/kotkoa/rickandmorty/blob/master/src/components/welcome/welcome.tsx"
    click Welcome "https://github.com/kotkoa/rickandmorty/blob/master/src/components/welcome/welcome.module.scss"
    click Favorites "https://github.com/kotkoa/rickandmorty/blob/master/src/components/show-favorite-list/show-favorite-list.tsx"
    click Favorites "https://github.com/kotkoa/rickandmorty/blob/master/src/components/show-favorite-list/show-favorite-list.module.scss"
    click Interesting "https://github.com/kotkoa/rickandmorty/blob/master/src/components/personajes-interesantes/personajes-interesantes.tsx"
    click Interesting "https://github.com/kotkoa/rickandmorty/blob/master/src/components/personajes-interesantes/personajes-interesantes.module.scss"
    click Router "https://github.com/kotkoa/rickandmorty/blob/master/src/routes/app-router.tsx"
    click JotaiStore "https://github.com/kotkoa/rickandmorty/blob/master/src/store/characters.store.ts"
    click ApolloClient "https://github.com/kotkoa/rickandmorty/blob/master/src/apolloClient/apollo-client.ts"
    click GenHooks "https://github.com/kotkoa/rickandmorty/blob/master/src/generated/graphql.tsx"
    click GenTypes "https://github.com/kotkoa/rickandmorty/blob/master/src/generated/graphql.d.ts"
    click Queries "https://github.com/kotkoa/rickandmorty/blob/master/src/queries/queries.gql"
    click Main "https://github.com/kotkoa/rickandmorty/blob/master/src/main.tsx"
    click Root "https://github.com/kotkoa/rickandmorty/blob/master/src/root.tsx"
    click Fonts "https://github.com/kotkoa/rickandmorty/tree/master/src/assets/fonts/Montserrat"
    click Icons "https://github.com/kotkoa/rickandmorty/tree/master/src/icons"
    click GlobalCSS "https://github.com/kotkoa/rickandmorty/blob/master/src/styles/index.css"
    click Tests "https://github.com/kotkoa/rickandmorty/blob/master/src/__tests__/App.test.tsx"

    %% Styles
    classDef ui fill:#BBE1FA,stroke:#0366d6
    classDef state fill:#A8D5BA,stroke:#228B22
    classDef data fill:#FFC68A,stroke:#DAA520
    classDef tooling fill:#D3D3D3,stroke:#696969
    classDef external fill:#FFB3B3,stroke:#B22222
    classDef asset fill:#E2E2F5,stroke:#6A5ACD
```
