# juan0diaz/app-read-now architecture

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

- Interactive diagram: https://gitdiagram.com/juan0diaz/app-read-now
- Repository: https://github.com/juan0diaz/app-read-now

## Overview

#### Purpose and entry points
This is a library/publication management system with a React/Vite frontend and ASP.NET Core API over Supabase Postgres. The browser starts at `src/main.tsx` and composes application routing/UI via `src/App.tsx`. The API starts at `backend/Program.cs`; its HTTP surface is controller-based.

#### Frontend application shell
`src/App.tsx` coordinates page-level navigation for public catalog, authentication, profiles, favorites, loans, publishing, and administration. `src/components/Layout.tsx` provides shared application framing. Key role-oriented screens are `src/pages/PublisherDashboard.tsx` and `src/pages/AdminDashboard.tsx`; catalog interaction begins in `src/pages/Home.tsx` and `src/pages/BookDetail.tsx`.

#### Authentication and authorization boundary
Supabase Auth remains client-owned: `src/lib/supabase.ts` and `src/context/AuthContext.tsx` manage login, registration, OAuth callback, and session state. The API receives Supabase-issued JWTs, validates them, and converts application roles into claims through `backend/Auth/RoleClaimsTransformation.cs`. This separates identity issuance from business-data authorization.

#### API and business-data boundary
The frontend should use `src/lib/api.ts` for authenticated API calls rather than querying Supabase tables directly. ASP.NET controllers expose the main resource boundaries: books in `backend/Controllers/LibrosController.cs`, publications in `backend/Controllers/PublicacionesController.cs`, favorites in `backend/Controllers/FavoritosController.cs`, and users/genres through `backend/Controllers/UsuariosController.cs` and `backend/Controllers/GenerosController.cs`. API permissions distinguish Visualizador, Publicador, and Administrador roles.

#### Persistence model
Entity Framework Core maps the application domain through `backend/Data/AppDbContext.cs` to Supabase Postgres. Central records include books, genres, publications, users, roles, favorites, and loan associations: `backend/Models/Libro.cs`, `backend/Models/Publicacion.cs`, and `backend/Models/UsuarioPrestamo.cs`. Request/response shape is decoupled from entities using `backend/Dtos/LibroDtos.cs` and `backend/Dtos/PublicacionDtos.cs`.

#### Primary flows
Catalog reads flow browser page → `src/lib/api.ts` → protected/public API controller → `AppDbContext` → Postgres. Publishing and administration follow the same path but require role claims resolved from user-role tables. Authentication flows browser → Supabase Auth → client session/JWT; subsequent API requests carry that JWT. Favorites and loan/profile functions operate on user-associated records after API authorization.

#### Runtime and infrastructure
Frontend runs on Node.js with Vite, normally port 3000 (`package.json`, `vite.config.ts`). Backend runs on .NET/ASP.NET Core, normally port 5080 (`backend/Backend.Api.csproj`, `backend/Program.cs`). Supabase supplies both Auth and hosted Postgres. Codespaces/devcontainer startup generates frontend environment variables and API URL from secrets via `.devcontainer/devcontainer.json` and `.devcontainer/scripts/generate-env.sh`; backend secrets are read from environment rather than committed configuration.

Main entry points: [`src/App.tsx`](https://github.com/juan0diaz/app-read-now/blob/main/src/App.tsx) (App routing), [`backend/Program.cs`](https://github.com/juan0diaz/app-read-now/blob/main/backend/Program.cs) (API entry), [`backend/Data/AppDbContext.cs`](https://github.com/juan0diaz/app-read-now/blob/main/backend/Data/AppDbContext.cs) (EF Core context), [`src/lib/api.ts`](https://github.com/juan0diaz/app-read-now/blob/main/src/lib/api.ts) (Authenticated API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_browser(("Browser client<br/>runtime"))
  node_main["Frontend entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app["App routing<br/>React shell<br/>[App.tsx]"]
  node_layout["Shared layout<br/>UI framing<br/>[Layout.tsx]"]
  node_catalog["Catalog screens<br/>public UI<br/>[Home.tsx]"]
  node_role_screens["Publisher &amp; admin screens<br/>role UI"]
  node_auth_client["Client auth session<br/>Supabase Auth client<br/>[AuthContext.tsx]"]
  node_api_client["Authenticated API client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_backend["ASP.NET Core API"]
  node_api_host["API entry<br/>ASP.NET Core host<br/>[Program.cs]"]
  node_controllers["Resource controllers<br/>HTTP controllers"]
  node_role_claims["Role claims transform<br/>authorization"]
  node_dto["Book &amp; publication DTOs<br/>API contracts<br/>[LibroDtos.cs]"]
  node_db_context["EF Core context<br/>persistence mapping<br/>[AppDbContext.cs]"]
  node_domain["Domain entities<br/>EF entities<br/>[Libro.cs]"]
end

subgraph group_supabase["Supabase"]
  node_supabase_auth{{"Supabase Auth<br/>identity provider"}}
  node_postgres[("Supabase Postgres<br/>hosted database")]
end

node_dev_setup["Dev environment setup<br/>Codespaces bootstrap<br/>[devcontainer.json]"]

node_browser -->|"loads"| node_main
node_main -->|"mounts"| node_app
node_app -->|"uses"| node_layout
node_app -->|"routes to"| node_catalog
node_app -->|"routes to"| node_role_screens
node_app -->|"reads session"| node_auth_client
node_catalog -->|"catalog requests"| node_api_client
node_role_screens -->|"role-protected requests"| node_api_client
node_auth_client -->|"login and OAuth"| node_supabase_auth
node_auth_client -->|"supplies JWT"| node_api_client
node_api_client -->|"authenticated HTTP"| node_api_host
node_api_host -->|"routes requests"| node_controllers
node_api_host -->|"validates JWT and resolves roles"| node_role_claims
node_controllers -->|"uses contracts"| node_dto
node_controllers -->|"reads and writes"| node_db_context
node_role_claims -->|"reads user roles"| node_db_context
node_db_context -->|"maps"| node_domain
node_db_context -->|"EF Core access"| node_postgres
node_dev_setup -.->|"generates environment"| node_main
node_dev_setup -.->|"provides secrets"| node_api_host

click node_main "https://github.com/juan0diaz/app-read-now/blob/main/src/main.tsx"
click node_app "https://github.com/juan0diaz/app-read-now/blob/main/src/App.tsx"
click node_layout "https://github.com/juan0diaz/app-read-now/blob/main/src/components/Layout.tsx"
click node_catalog "https://github.com/juan0diaz/app-read-now/blob/main/src/pages/Home.tsx"
click node_role_screens "https://github.com/juan0diaz/app-read-now/blob/main/src/pages/PublisherDashboard.tsx"
click node_auth_client "https://github.com/juan0diaz/app-read-now/blob/main/src/context/AuthContext.tsx"
click node_api_client "https://github.com/juan0diaz/app-read-now/blob/main/src/lib/api.ts"
click node_api_host "https://github.com/juan0diaz/app-read-now/blob/main/backend/Program.cs"
click node_controllers "https://github.com/juan0diaz/app-read-now/blob/main/backend/Controllers/LibrosController.cs"
click node_role_claims "https://github.com/juan0diaz/app-read-now/blob/main/backend/Auth/RoleClaimsTransformation.cs"
click node_dto "https://github.com/juan0diaz/app-read-now/blob/main/backend/Dtos/LibroDtos.cs"
click node_db_context "https://github.com/juan0diaz/app-read-now/blob/main/backend/Data/AppDbContext.cs"
click node_domain "https://github.com/juan0diaz/app-read-now/blob/main/backend/Models/Libro.cs"
click node_dev_setup "https://github.com/juan0diaz/app-read-now/blob/main/.devcontainer/devcontainer.json"

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_browser,node_main,node_app,node_layout,node_catalog,node_role_screens,node_auth_client,node_api_client toneBlue
class node_api_host,node_controllers,node_role_claims,node_dto,node_db_context,node_domain toneAmber
class node_supabase_auth,node_postgres toneMint
class node_dev_setup toneNeutral
```

## Components

### React frontend

Browser application on Vite.

- **Browser client**: runtime
- [Frontend entry](https://github.com/juan0diaz/app-read-now/blob/main/src/main.tsx): React bootstrap · `src/main.tsx`
- [App routing](https://github.com/juan0diaz/app-read-now/blob/main/src/App.tsx): React shell · Coordinates catalog, account, publishing, and admin navigation. · `src/App.tsx`
- [Shared layout](https://github.com/juan0diaz/app-read-now/blob/main/src/components/Layout.tsx): UI framing · `src/components/Layout.tsx`
- [Catalog screens](https://github.com/juan0diaz/app-read-now/blob/main/src/pages/Home.tsx): public UI · Home and book-detail interaction. · `src/pages/Home.tsx`
- [Publisher & admin screens](https://github.com/juan0diaz/app-read-now/blob/main/src/pages/PublisherDashboard.tsx): role UI · `src/pages/PublisherDashboard.tsx`
- [Client auth session](https://github.com/juan0diaz/app-read-now/blob/main/src/context/AuthContext.tsx): Supabase Auth client · Manages login, OAuth callback, and JWT session state. · `src/context/AuthContext.tsx`
- [Authenticated API client](https://github.com/juan0diaz/app-read-now/blob/main/src/lib/api.ts): HTTP client · Frontend boundary for business-data calls. · `src/lib/api.ts`

### ASP.NET Core API

Controller-based business API.

- [API entry](https://github.com/juan0diaz/app-read-now/blob/main/backend/Program.cs): ASP.NET Core host · `backend/Program.cs`
- [Resource controllers](https://github.com/juan0diaz/app-read-now/blob/main/backend/Controllers/LibrosController.cs): HTTP controllers · Books, publications, favorites, users, and genres endpoints. · `backend/Controllers/LibrosController.cs`
- [Role claims transform](https://github.com/juan0diaz/app-read-now/blob/main/backend/Auth/RoleClaimsTransformation.cs): authorization · Maps application roles to authorization claims. · `backend/Auth/RoleClaimsTransformation.cs`
- [Book & publication DTOs](https://github.com/juan0diaz/app-read-now/blob/main/backend/Dtos/LibroDtos.cs): API contracts · Decouple request and response shapes from entities. · `backend/Dtos/LibroDtos.cs`
- [EF Core context](https://github.com/juan0diaz/app-read-now/blob/main/backend/Data/AppDbContext.cs): persistence mapping · Maps domain records and associations to Postgres. · `backend/Data/AppDbContext.cs`
- [Domain entities](https://github.com/juan0diaz/app-read-now/blob/main/backend/Models/Libro.cs): EF entities · Books, publications, and user-loan associations. · `backend/Models/Libro.cs`

### Supabase

Managed identity and Postgres.

- **Supabase Auth**: identity provider · Issues client session JWTs.
- **Supabase Postgres**: hosted database · Stores books, publications, users, roles, favorites, and loans.

### Other components

- [Dev environment setup](https://github.com/juan0diaz/app-read-now/blob/main/.devcontainer/devcontainer.json): Codespaces bootstrap · Generates frontend environment and API URL from secrets. · `.devcontainer/devcontainer.json`

## Connections

- Browser client → Frontend entry: loads
- Frontend entry → App routing: mounts
- App routing → Shared layout: uses
- App routing → Catalog screens: routes to
- App routing → Publisher & admin screens: routes to
- App routing → Client auth session: reads session
- Catalog screens → Authenticated API client: catalog requests
- Publisher & admin screens → Authenticated API client: role-protected requests
- Client auth session → Supabase Auth: login and OAuth
- Client auth session → Authenticated API client: supplies JWT
- Authenticated API client → API entry: authenticated HTTP
- API entry → Resource controllers: routes requests
- API entry → Role claims transform: validates JWT and resolves roles
- Resource controllers → Book & publication DTOs: uses contracts
- Resource controllers → EF Core context: reads and writes
- Role claims transform → EF Core context: reads user roles
- EF Core context → Domain entities: maps
- EF Core context → Supabase Postgres: EF Core access
- Dev environment setup → Frontend entry: generates environment
- Dev environment setup → API entry: provides secrets