# interview-repo/evreka architecture

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

- Interactive diagram: https://gitdiagram.com/interview-repo/evreka
- Repository: https://github.com/interview-repo/evreka

## Overview

##### Project Type and Purpose
- This is a Single-Page Application (SPA) user management interface (“Evreka Users CRM”) built entirely in React + TypeScript.
- It does not include a real backend; instead it uses MSW (Mock Service Worker) to simulate a REST API for development.
- Key features: list of 5,000+ users (table/card), filtering, pagination modes, modal forms, URL-state management, Leaflet maps, localStorage persistence.

##### File Structure
- Top-level Vite config & package files → your build/development toolchain.
- public/ → static assets, service worker, manifest.
- src/
- api/ → HTTP client setup (createApiClient).
- components/ → UI primitives & domain widgets (form controls, table, user cards, modal, map components).
- hooks/ → abstraction over data fetching & UI state (useApi/useApiTable via TanStack Query, user-specific hooks).
- integrations/ → TanStack-Query and Router providers & layout wrappers.
- routes/ → page components wired to URL paths (root, user list, user detail).
- mock/ → MSW handlers & fake data generator (Faker.js).
- utils/ → misc helpers (date formatting, validation, localStorage).
- types/ & constants/ → strongly-typed models & enums.
- styles.css → global CSS (Tailwind + Styled Components).

##### Gather Insights from the README
- Confirms use of React 19, TypeScript strict mode, TanStack Query/Router, Styled Components + Tailwind, Leaflet, Zod validation.
- Clarifies functional domains: user listing, filtering/searching, modal form flows, detail page with interactive map.

- Browser (Client)
- React App
– Routing Layer (TanStack Router)
– State & Data Layer (TanStack Query)
– UI Layer (Components tree)
· Shared components (buttons, inputs, table, cards, map)
· Domain components (UserListPage, UserDetailPage)
– Integration Layer
· API Client (axios/fetch wrapper)
· Mock Service Worker (msw) intercepting API calls
· LocalStorage persistence adapter
· Zod schema validator for form inputs
· Leaflet map controller connecting to external tile server
- Mock API (MSW)
- Endpoint handlers returning fake users from mock/user.service.ts
- Generator seeded with Faker.js
- External Services
- Tile Server (e.g., OpenStreetMap)
- Data Flow
- UI dispatches queries via useApi/useApiTable → TanStack Query cache → API Client → MSW → mock data
- Form submissions validated by Zod → API Client calls → MSW update
- Query results optionally synced to localStorage (URL-based state)
- Build/Dev
- Vite Dev Server serves React App, registers MSW
- Yarn scripts for build, preview, lint

##### Architectural Patterns & Design Principles
- Component-Driven Architecture: small, reusable UI building blocks.
- Hooks for separation of concerns: data fetching vs. UI logic.
- Provider pattern: central TanStack Query/Router providers wrapping the app.
- Mocking layer decoupled from production API (swap MSW for real endpoints).
- URL-driven state & localStorage persistence for shareable links & reload resilience.

##### Elements
- Clear component names matching the file tree (e.g., “UserListPage”, “useUsersTable” hook).
- Infrastructure nodes: Vite Dev Server, MSW service worker, Browser LocalStorage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UserListPage["UserListPage"]:::frontend
        UserDetailPage["UserDetailPage"]:::frontend
        SharedUI["Shared UI Primitives"]:::frontend
        FormControls["Form Controls"]:::frontend
        TableComponents["Table & Pagination"]:::frontend
        UserWidgets["User Widgets"]:::frontend
        MapComponents["Map Components"]:::frontend
    end

    %% Data & State Layer
    subgraph "Data & State Layer"
        direction TB
        useApi["useApi"]:::data
        useApiTable["useApiTable"]:::data
        useUsersList["useUsersList"]:::data
        useUsersTable["useUsersTable"]:::data
        useUserForm["useUserForm"]:::data
        useUserModal["useUserModal"]:::data
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        TanStackQueryProvider["TanStack Query Provider"]:::integration
        TanStackQueryLayout["TanStack Query Layout"]:::integration
        RouterLayer["Routing Layer (TanStack Router)"]:::integration
    end

    %% API & Mock Layer
    subgraph "API & Mock Layer"
        direction TB
        ApiClient["API Client"]:::integration
        MSWWorker["MSW Service Worker"]:::mock
        MSWHandlers["MSW Handlers"]:::mock
        MockGenerator["Mock Data Generator"]:::mock
    end

    %% External & Utilities
    subgraph "External & Utilities"
        direction TB
        LocalStorage[(Browser LocalStorage)]:::storage
        ZodValidation["Zod Validation Schema"]:::util
        TileServer{Map Tile Server}:::external
    end

    %% Data Flow Connections
    UserListPage -->|uses| useUsersTable
    UserDetailPage -->|uses| useUserForm
    UserListPage -->|uses| useUsersList
    SharedUI -->|used by| UserListPage
    FormControls -->|used by| UserDetailPage
    TableComponents -->|used by| UserListPage
    UserWidgets -->|used by| UserListPage
    MapComponents -->|used by| UserDetailPage

    useUsersList -->|calls| useApi
    useUsersTable -->|calls| useApiTable
    useApi -->|requests| ApiClient
    useApiTable -->|requests| ApiClient

    ApiClient -->|REST GET/POST| MSWWorker
    MSWWorker -->|routes to| MSWHandlers
    MSWHandlers -->|generates data| MockGenerator
    MSWHandlers -->|returns mock response| ApiClient

    UserDetailPage -->|validates form| ZodValidation
    ZodValidation -->|on valid| ApiClient

    TanStackQueryProvider -->|wraps| UserListPage
    TanStackQueryProvider -->|wraps| UserDetailPage
    TanStackQueryLayout -->|layout| UserListPage
    RouterLayer -->|routes| UserListPage
    RouterLayer -->|routes| UserDetailPage

    useUsersTable -->|syncs| LocalStorage
    useUsersList -->|syncs| LocalStorage

    MapComponents -->|fetch tiles| TileServer

    %% Click Events
    click ApiClient "https://github.com/interview-repo/evreka/blob/main/src/api/client.ts"
    click MSWWorker "https://github.com/interview-repo/evreka/blob/main/public/mockServiceWorker.js"
    click MSWHandlers "https://github.com/interview-repo/evreka/blob/main/src/mock/index.ts"
    click MSWHandlers "https://github.com/interview-repo/evreka/blob/main/src/mock/user.service.ts"
    click MockGenerator "https://github.com/interview-repo/evreka/blob/main/src/mock/generator.ts"
    click RouterLayer "https://github.com/interview-repo/evreka/blob/main/src/routeTree.gen.ts"
    click UserListPage "https://github.com/interview-repo/evreka/blob/main/src/routes/index.tsx"
    click UserDetailPage "https://github.com/interview-repo/evreka/blob/main/src/routes/users.$userId.tsx"
    click TanStackQueryProvider "https://github.com/interview-repo/evreka/blob/main/src/integrations/tanstack-query/root-provider.tsx"
    click TanStackQueryLayout "https://github.com/interview-repo/evreka/blob/main/src/integrations/tanstack-query/layout.tsx"
    click useApi "https://github.com/interview-repo/evreka/blob/main/src/hooks/shared/useApi.ts"
    click useApiTable "https://github.com/interview-repo/evreka/blob/main/src/hooks/shared/useApiTable.tsx"
    click useUsersList "https://github.com/interview-repo/evreka/blob/main/src/hooks/users/useUsersList.tsx"
    click useUsersTable "https://github.com/interview-repo/evreka/blob/main/src/hooks/users/useUsersTable.ts"
    click useUserForm "https://github.com/interview-repo/evreka/blob/main/src/hooks/users/useUserForm.ts"
    click useUserModal "https://github.com/interview-repo/evreka/blob/main/src/hooks/users/useUserModal.ts"
    click SharedUI "https://github.com/interview-repo/evreka/tree/main/src/components/shared/"
    click FormControls "https://github.com/interview-repo/evreka/tree/main/src/components/form/"
    click TableComponents "https://github.com/interview-repo/evreka/tree/main/src/components/table/"
    click UserWidgets "https://github.com/interview-repo/evreka/tree/main/src/components/user/"
    click MapComponents "https://github.com/interview-repo/evreka/tree/main/src/components/location/"
    click LocalStorage "https://github.com/interview-repo/evreka/blob/main/src/utils/localStorage.ts"
    click ZodValidation "https://github.com/interview-repo/evreka/blob/main/src/utils/userFormValidation.ts"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef data fill:#E8FCEF,stroke:#28A745,color:#28A745;
    classDef integration fill:#FFF4E5,stroke:#D9822B,color:#D9822B;
    classDef mock fill:#E6F7FF,stroke:#1D70B8,color:#1D70B8;
    classDef external fill:#FFF5F5,stroke:#D73A49,color:#D73A49;
    classDef storage fill:#FFFDF0,stroke:#B08800,color:#B08800;
    classDef util fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
