# readrace-ages/readrace architecture

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

- Interactive diagram: https://gitdiagram.com/readrace-ages/readrace
- Repository: https://github.com/readrace-ages/readrace

## Overview

ReadRace is a mobile reading-habit app using casual gamification. Readers browse books, manage reading lists and progress, then participate in friend challenges, clubs, forums, and community feeds. The mobile app’s feature hooks call its API modules and shared HTTP client; backend controllers delegate to services, which access persistence or book-search adapters. The README documents PostgreSQL and the Google Books integration. Sampled code confirms book-search and library paths; other feature wiring is represented only where supported by the tree and documented product structure.

Main entry points: [`mobile/src/app`](https://github.com/readrace-ages/readrace/tree/dev/mobile/src/app) (App routes), [`backend/src/main/java/com/readrace/api/controller`](https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/controller) (REST controllers), [`mobile/src/api/client.ts`](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/api/client.ts) (HTTP client), [`backend/src/main/java/com/readrace/api/repository`](https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/repository) (Data repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile experience"]
  node_mobile_routes["App routes"]
  node_http_client["HTTP client<br/>[client.ts]"]
  node_library_ui["My books<br/>[MeusLivrosView.tsx]"]
  node_library_hook["Library state<br/>[useBiblioteca.ts]"]
  node_book_search_ui["Book search<br/>[BuscaView.tsx]"]
  node_book_detail_ui["Book details"]
  node_community_ui["Community screens"]
  node_challenge_ui["Challenges<br/>[DesafioScreen.tsx]"]
end

subgraph group_api["Backend API"]
  node_api_controllers["REST controllers"]
  node_book_controller["Book endpoint"]
  node_book_service["Book search service<br/>[BookService.java]"]
  node_library_service["Library service"]
  node_book_detail_service["Book detail service<br/>[LivroService.java]"]
  node_challenge_service["Challenge service"]
  node_community_services["Community services"]
end

subgraph group_domain["Reading community"]
end

subgraph group_integrations["Persistence and search"]
  node_book_port["Search port"]
  node_local_search["Local catalog"]
  node_google_search["Google Books"]
  node_repositories["Data repositories"]
  node_postgres[("PostgreSQL")]
end

node_reader(("Reader"))

node_reader -->|"uses"| node_mobile_routes
node_mobile_routes -->|"opens"| node_library_ui
node_mobile_routes -->|"opens"| node_book_search_ui
node_mobile_routes -->|"opens"| node_book_detail_ui
node_mobile_routes -->|"opens"| node_community_ui
node_mobile_routes -->|"opens"| node_challenge_ui
node_library_ui -->|"reads state"| node_library_hook
node_library_hook -->|"requests pages"| node_http_client
node_book_search_ui -->|"requests search"| node_http_client
node_book_detail_ui -->|"requests details"| node_http_client
node_community_ui -->|"requests feed"| node_http_client
node_challenge_ui -->|"requests challenges"| node_http_client
node_http_client -->|"sends HTTP"| node_api_controllers
node_api_controllers -->|"delegates"| node_library_service
node_api_controllers -->|"delegates"| node_book_detail_service
node_api_controllers -->|"delegates"| node_community_services
node_api_controllers -->|"delegates"| node_challenge_service
node_api_controllers -->|"routes search"| node_book_controller
node_book_controller -->|"delegates"| node_book_service
node_book_service -->|"searches"| node_book_port
node_book_port -->|"dispatches"| node_local_search
node_book_port -.->|"dispatches"| node_google_search
node_library_service -->|"queries"| node_repositories
node_book_detail_service -->|"queries"| node_repositories
node_challenge_service -->|"queries"| node_repositories
node_community_services -->|"queries"| node_repositories
node_repositories -->|"reads/writes"| node_postgres

click node_mobile_routes "https://github.com/readrace-ages/readrace/tree/dev/mobile/src/app"
click node_http_client "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/api/client.ts"
click node_library_ui "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/biblioteca/MeusLivrosView.tsx"
click node_library_hook "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/biblioteca/useBiblioteca.ts"
click node_book_search_ui "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/busca/BuscaView.tsx"
click node_book_detail_ui "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/livro/LivroDetalheScreen.tsx"
click node_community_ui "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/feed/FeedComunidadesView.tsx"
click node_challenge_ui "https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/desafios/DesafioScreen.tsx"
click node_api_controllers "https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/controller"
click node_book_controller "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/controller/BookController.java"
click node_book_service "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BookService.java"
click node_library_service "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BibliotecaService.java"
click node_book_detail_service "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/LivroService.java"
click node_challenge_service "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/DesafioService.java"
click node_community_services "https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/service"
click node_book_port "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BookSearchPort.java"
click node_local_search "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/adapter/local/LocalBooksAdapter.java"
click node_google_search "https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/adapter/google/GoogleBooksAdapter.java"
click node_repositories "https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/repository"

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_mobile_routes,node_http_client,node_library_ui,node_library_hook,node_book_search_ui,node_book_detail_ui,node_community_ui,node_challenge_ui toneBlue
class node_api_controllers,node_book_controller,node_book_service,node_library_service,node_book_detail_service,node_challenge_service,node_community_services toneAmber
class node_book_port,node_local_search,node_google_search,node_repositories,node_postgres toneRose
class node_reader toneIndigo
```

## Components

### Mobile experience

- [App routes](https://github.com/readrace-ages/readrace/tree/dev/mobile/src/app): `mobile/src/app`
- [HTTP client](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/api/client.ts): `mobile/src/api/client.ts`
- [My books](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/biblioteca/MeusLivrosView.tsx): `mobile/src/features/biblioteca/MeusLivrosView.tsx`
- [Library state](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/biblioteca/useBiblioteca.ts): `mobile/src/features/biblioteca/useBiblioteca.ts`
- [Book search](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/busca/BuscaView.tsx): `mobile/src/features/busca/BuscaView.tsx`
- [Book details](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/livro/LivroDetalheScreen.tsx): `mobile/src/features/livro/LivroDetalheScreen.tsx`
- [Community screens](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/feed/FeedComunidadesView.tsx): `mobile/src/features/feed/FeedComunidadesView.tsx`
- [Challenges](https://github.com/readrace-ages/readrace/blob/dev/mobile/src/features/desafios/DesafioScreen.tsx): `mobile/src/features/desafios/DesafioScreen.tsx`

### Backend API

- [REST controllers](https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/controller): `backend/src/main/java/com/readrace/api/controller`
- [Book endpoint](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/controller/BookController.java): `backend/src/main/java/com/readrace/api/controller/BookController.java`
- [Book search service](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BookService.java): `backend/src/main/java/com/readrace/api/service/BookService.java`
- [Library service](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BibliotecaService.java): `backend/src/main/java/com/readrace/api/service/BibliotecaService.java`
- [Book detail service](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/LivroService.java): `backend/src/main/java/com/readrace/api/service/LivroService.java`
- [Challenge service](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/DesafioService.java): `backend/src/main/java/com/readrace/api/service/DesafioService.java`
- [Community services](https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/service): `backend/src/main/java/com/readrace/api/service`

### Persistence and search

- [Search port](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/service/BookSearchPort.java): `backend/src/main/java/com/readrace/api/service/BookSearchPort.java`
- [Local catalog](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/adapter/local/LocalBooksAdapter.java): `backend/src/main/java/com/readrace/api/adapter/local/LocalBooksAdapter.java`
- [Google Books](https://github.com/readrace-ages/readrace/blob/dev/backend/src/main/java/com/readrace/api/adapter/google/GoogleBooksAdapter.java): `backend/src/main/java/com/readrace/api/adapter/google/GoogleBooksAdapter.java`
- [Data repositories](https://github.com/readrace-ages/readrace/tree/dev/backend/src/main/java/com/readrace/api/repository): `backend/src/main/java/com/readrace/api/repository`
- **PostgreSQL**

### Other components

- **Reader**

## Connections

- Reader → App routes: uses
- App routes → My books: opens
- App routes → Book search: opens
- App routes → Book details: opens
- App routes → Community screens: opens
- App routes → Challenges: opens
- My books → Library state: reads state
- Library state → HTTP client: requests pages
- Book search → HTTP client: requests search
- Book details → HTTP client: requests details
- Community screens → HTTP client: requests feed
- Challenges → HTTP client: requests challenges
- HTTP client → REST controllers: sends HTTP
- REST controllers → Library service: delegates
- REST controllers → Book detail service: delegates
- REST controllers → Community services: delegates
- REST controllers → Challenge service: delegates
- REST controllers → Book endpoint: routes search
- Book endpoint → Book search service: delegates
- Book search service → Search port: searches
- Search port → Local catalog: dispatches
- Search port → Google Books: dispatches
- Library service → Data repositories: queries
- Book detail service → Data repositories: queries
- Challenge service → Data repositories: queries
- Community services → Data repositories: queries
- Data repositories → PostgreSQL: reads/writes