# alonsodelrio/bookmark-manager architecture

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

- Interactive diagram: https://gitdiagram.com/alonsodelrio/bookmark-manager
- Repository: https://github.com/alonsodelrio/bookmark-manager

## Overview

1. **High-level shape**
   - This repo is a three-part system: a **React frontend**, a **FastAPI backend**, and **Supabase** as the managed auth/database layer.
   - The frontend owns the user experience, the backend owns business logic and secret-bearing operations, and Supabase stores user/session state and bookmark data.

2. **Frontend responsibilities**
   - The UI lives under `frontend/src` and is organized around two pages: `AuthPage` for sign-in/sign-up and `DashboardPage` for the bookmark workspace.
   - Reusable bookmark and layout components handle the modal forms, cards, filters, sidebar, and header; styling is isolated with CSS Modules.

3. **Client-side state and API access**
   - `useAuth.tsx` manages the Supabase session and auth state across the app.
   - `useBookmarks.ts` uses TanStack Query for server state, including query caching, mutations, and optimistic updates.
   - `lib/api.ts` is the FastAPI client; it injects the user JWT so authenticated requests flow from browser to backend securely.

4. **Authentication boundary**
   - The frontend talks **directly to Supabase Auth** via the Supabase JS SDK for sign-in, sign-up, and sign-out.
   - The frontend does **not** talk directly to the database; it only sends the Supabase JWT to FastAPI as a Bearer token.
   - This keeps the Supabase service-role key off the client and makes the backend the only trusted place for privileged operations.

5. **Backend API layer**
   - FastAPI routes are split by concern in `backend/app/routers`: `bookmarks.py`, `tags.py`, and `metadata.py`.
   - `main.py` wires the app together, while `core/config.py` and `core/supabase.py` centralize settings, Supabase client setup, and auth dependencies.
   - The backend is the only component that performs server-side validation, filtering, and access control decisions for bookmark data.

6. **Bookmark data flow**
   - Bookmark CRUD requests go from the frontend to FastAPI, then from FastAPI to Supabase/Postgres using the service-role key.
   - The backend filters every query by user identity, and the database also enforces ownership through RLS policies in `supabase/schema.sql`.
   - Tags are stored as an array on the bookmark row, so tag operations are lightweight but not fully normalized.

7. **Metadata extraction path**
   - `metadata.py` is a separate backend service used when creating or previewing bookmarks.
   - It fetches arbitrary target URLs server-side, parses HTML for title/favicon metadata, and falls back gracefully when the site is unreachable or non-HTML.
   - This work stays in FastAPI rather than the browser to avoid SSRF risk, CORS issues, and exposure of external fetch logic to the client.

8. **Database and security model**
   - Supabase provides **Postgres + Auth**; the schema file defines the bookmark table and RLS policies.
   - RLS is the primary security boundary in the database, using the JWT-derived user identity so each user only sees their own rows.
   - Backend-side user filtering is a second layer of protection, not the first.

9. **Shared contracts**
   - `backend/app/schemas` defines backend response shapes, while `frontend/src/types` mirrors the data contracts used by the UI.
   - This keeps the frontend and backend aligned without sharing code directly across runtime boundaries.

10. **Runtime and deployment**
   - The app is containerized with Docker and orchestrated locally with `docker-compose.yml` and `docker-compose.dev.yml`.
   - The frontend production container serves the built app through Nginx; the backend runs as a separate FastAPI container.
   - Railway is the target deployment platform referenced in the README.

11. **Quality and validation**
   - Backend tests focus heavily on metadata extraction behavior, especially fallback paths and failure handling.
   - CI in `.github/workflows/ci.yml` runs backend lint/tests, frontend type-checking and linting, and Docker build smoke tests.
   - This reflects the architecture’s main risk areas: external HTTP fetching, auth correctness, and cross-service build integrity.

Main entry points: [`backend/app/main.py`](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/pages/DashboardPage.tsx`](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/pages/DashboardPage.tsx) (Dashboard), [`frontend/src/App.tsx`](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/App.tsx) (App shell), [`backend/app/routers/bookmarks.py`](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/bookmarks.py) (Bookmark routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React entry<br/>[App.tsx]"]
  node_frontend_auth["Auth page<br/>UI page<br/>[AuthPage.tsx]"]
  node_frontend_dashboard["Dashboard<br/>UI page<br/>[DashboardPage.tsx]"]
  node_frontend_bookmark_ui["Bookmark UI<br/>UI components"]
  node_frontend_layout["Layout UI<br/>UI components"]
  node_frontend_useauth(("Auth state<br/>React hook<br/>[useAuth.tsx]"))
  node_frontend_usebookmarks(("Bookmarks state<br/>Query hook<br/>[useBookmarks.ts]"))
  node_frontend_api["API client<br/>HTTP client<br/>[api.ts]"]
  node_frontend_supabase["Supabase client<br/>Auth SDK<br/>[supabase.ts]"]
  node_frontend_types["Shared types<br/>Contracts<br/>[index.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>API entry<br/>[main.py]"]
  node_backend_config["Backend config<br/>Settings<br/>[config.py]"]
  node_backend_supabase["Supabase backend<br/>Client/auth<br/>[supabase.py]"]
  node_backend_bookmarks["Bookmark routes<br/>Router<br/>[bookmarks.py]"]
  node_backend_tags["Tag routes<br/>Router<br/>[tags.py]"]
  node_backend_metadata["Metadata route<br/>Router<br/>[metadata.py]"]
  node_backend_bookmark_svc["Bookmark service<br/>[bookmark.py]"]
  node_backend_metadata_svc["Metadata service<br/>[metadata.py]"]
  node_backend_schema["Bookmark schema<br/>Pydantic models<br/>[bookmark.py]"]
end

subgraph group_supabase["Supabase"]
  node_supabase_schema["DB schema<br/>SQL schema<br/>[schema.sql]"]
end

subgraph group_infra["Infra"]
  node_ci["CI pipeline<br/>Workflow<br/>[ci.yml]"]
  node_compose["Compose setup<br/>Orchestration<br/>[docker-compose.yml]"]
  node_compose_dev["Dev compose<br/>Orchestration"]
  node_frontend_docker["Frontend image<br/>Container"]
  node_backend_docker["Backend image<br/>Container"]
end

node_frontend_app -->|"routes to"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_dashboard
node_frontend_auth -->|"auth calls"| node_frontend_supabase
node_frontend_app -->|"session state"| node_frontend_useauth
node_frontend_dashboard -->|"data state"| node_frontend_usebookmarks
node_frontend_dashboard -->|"composes"| node_frontend_bookmark_ui
node_frontend_dashboard -->|"uses shell"| node_frontend_layout
node_frontend_usebookmarks -->|"requests"| node_frontend_api
node_frontend_api -->|"Bearer JWT"| node_backend_main
node_backend_main -->|"mounts"| node_backend_bookmarks
node_backend_main -->|"mounts"| node_backend_tags
node_backend_main -->|"mounts"| node_backend_metadata
node_backend_main -->|"loads"| node_backend_config
node_backend_main -->|"auth layer"| node_backend_supabase
node_backend_bookmarks -->|"delegates"| node_backend_bookmark_svc
node_backend_bookmarks -->|"validates"| node_backend_schema
node_backend_metadata -->|"delegates"| node_backend_metadata_svc
node_backend_bookmark_svc -->|"persists to"| node_supabase_schema
node_frontend_supabase -.->|"auth identity"| node_supabase_schema
node_supabase_schema -->|"RLS checks"| node_backend_supabase
node_frontend_types -.->|"mirrors"| node_backend_schema
node_ci -.->|"builds"| node_backend_docker
node_ci -.->|"builds"| node_frontend_docker
node_compose -->|"runs"| node_frontend_docker
node_compose -->|"runs"| node_backend_docker
node_compose_dev -->|"runs"| node_frontend_docker
node_compose_dev -->|"runs"| node_backend_docker

click node_frontend_app "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/App.tsx"
click node_frontend_auth "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/pages/AuthPage.tsx"
click node_frontend_dashboard "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_frontend_bookmark_ui "https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/src/components/bookmarks"
click node_frontend_layout "https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/src/components/layout"
click node_frontend_useauth "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/hooks/useAuth.tsx"
click node_frontend_usebookmarks "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/hooks/useBookmarks.ts"
click node_frontend_api "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/lib/api.ts"
click node_frontend_supabase "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/lib/supabase.ts"
click node_frontend_types "https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/types/index.ts"
click node_backend_main "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/core/config.py"
click node_backend_supabase "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/core/supabase.py"
click node_backend_bookmarks "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/bookmarks.py"
click node_backend_tags "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/tags.py"
click node_backend_metadata "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/metadata.py"
click node_backend_bookmark_svc "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/services/bookmark.py"
click node_backend_metadata_svc "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/services/metadata.py"
click node_backend_schema "https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/schemas/bookmark.py"
click node_supabase_schema "https://github.com/alonsodelrio/bookmark-manager/blob/main/supabase/schema.sql"
click node_ci "https://github.com/alonsodelrio/bookmark-manager/blob/main/.github/workflows/ci.yml"
click node_compose "https://github.com/alonsodelrio/bookmark-manager/blob/main/docker-compose.yml"
click node_compose_dev "https://github.com/alonsodelrio/bookmark-manager/blob/main/docker-compose.dev.yml"
click node_frontend_docker "https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/Dockerfile"
click node_backend_docker "https://github.com/alonsodelrio/bookmark-manager/tree/main/backend/Dockerfile"

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_app,node_frontend_auth,node_frontend_dashboard,node_frontend_bookmark_ui,node_frontend_layout,node_frontend_useauth,node_frontend_usebookmarks,node_frontend_api,node_frontend_supabase,node_frontend_types toneBlue
class node_backend_main,node_backend_config,node_backend_supabase,node_backend_bookmarks,node_backend_tags,node_backend_metadata,node_backend_bookmark_svc,node_backend_metadata_svc,node_backend_schema toneAmber
class node_supabase_schema toneMint
class node_ci,node_compose,node_compose_dev,node_frontend_docker,node_backend_docker toneRose
```

## Components

### Frontend

React UI, client state, and browser-side API/auth integration.

- [App shell](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/App.tsx): React entry · Wires providers and page-level app composition. · `frontend/src/App.tsx`
- [Auth page](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/pages/AuthPage.tsx): UI page · Sign-in and sign-up experience. · `frontend/src/pages/AuthPage.tsx`
- [Dashboard](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/pages/DashboardPage.tsx): UI page · Main bookmark workspace and page composition. · `frontend/src/pages/DashboardPage.tsx`
- [Bookmark UI](https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/src/components/bookmarks): UI components · Bookmark cards, modals, filters, and tag input. · `frontend/src/components/bookmarks`
- [Layout UI](https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/src/components/layout): UI components · Header and sidebar shell for the dashboard. · `frontend/src/components/layout`
- [Auth state](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/hooks/useAuth.tsx): React hook · Tracks Supabase session and auth state across the app. · `frontend/src/hooks/useAuth.tsx`
- [Bookmarks state](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/hooks/useBookmarks.ts): Query hook · Server state, caching, mutations, and optimistic updates for bookmarks. · `frontend/src/hooks/useBookmarks.ts`
- [API client](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/lib/api.ts): HTTP client · Calls FastAPI and injects the user JWT as Bearer auth. · `frontend/src/lib/api.ts`
- [Supabase client](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/lib/supabase.ts): Auth SDK · Browser-side Supabase Auth integration for sign-in, sign-up, and sign-out. · `frontend/src/lib/supabase.ts`
- [Shared types](https://github.com/alonsodelrio/bookmark-manager/blob/main/frontend/src/types/index.ts): Contracts · Frontend data contracts mirrored from backend schemas. · `frontend/src/types/index.ts`

### Backend

FastAPI routes, services, and server-side auth/validation.

- [FastAPI app](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/main.py): API entry · Application wiring and router registration. · `backend/app/main.py`
- [Backend config](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/core/config.py): Settings · Centralized settings and environment configuration. · `backend/app/core/config.py`
- [Supabase backend](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/core/supabase.py): Client/auth · Server-side Supabase client and auth dependencies. · `backend/app/core/supabase.py`
- [Bookmark routes](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/bookmarks.py): Router · CRUD and ownership-aware bookmark endpoints. · `backend/app/routers/bookmarks.py`
- [Tag routes](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/tags.py): Router · Tag-related bookmark operations and filtering support. · `backend/app/routers/tags.py`
- [Metadata route](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/routers/metadata.py): Router · Server-side URL fetch and metadata extraction endpoints. · `backend/app/routers/metadata.py`
- [Bookmark service](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/services/bookmark.py): Service · Business logic for bookmark validation and persistence. · `backend/app/services/bookmark.py`
- [Metadata service](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/services/metadata.py): Service · Fetches pages and extracts title/favicon metadata with fallbacks. · `backend/app/services/metadata.py`
- [Bookmark schema](https://github.com/alonsodelrio/bookmark-manager/blob/main/backend/app/schemas/bookmark.py): Pydantic models · Backend request/response shapes for bookmark data. · `backend/app/schemas/bookmark.py`

### Supabase

Managed Auth and Postgres layer with row-level security.

- [DB schema](https://github.com/alonsodelrio/bookmark-manager/blob/main/supabase/schema.sql): SQL schema · Bookmarks table and row-level security policies. · `supabase/schema.sql`

### Infra

Containerization, CI, and deployment wiring.

- [CI pipeline](https://github.com/alonsodelrio/bookmark-manager/blob/main/.github/workflows/ci.yml): Workflow · Runs backend lint/tests, frontend checks, and Docker smoke builds. · `.github/workflows/ci.yml`
- [Compose setup](https://github.com/alonsodelrio/bookmark-manager/blob/main/docker-compose.yml): Orchestration · Local multi-service startup for frontend, backend, and Supabase dependencies. · `docker-compose.yml`
- [Dev compose](https://github.com/alonsodelrio/bookmark-manager/blob/main/docker-compose.dev.yml): Orchestration · Development-oriented container composition. · `docker-compose.dev.yml`
- [Frontend image](https://github.com/alonsodelrio/bookmark-manager/tree/main/frontend/Dockerfile): Container · Builds the React app and serves it with Nginx. · `frontend/Dockerfile`
- [Backend image](https://github.com/alonsodelrio/bookmark-manager/tree/main/backend/Dockerfile): Container · Packages and runs the FastAPI service. · `backend/Dockerfile`

## Connections

- App shell → Auth page: routes to · App renders the auth flow when no session is present.
- App shell → Dashboard: routes to · App renders the workspace for authenticated users.
- Auth page → Supabase client: auth calls · Uses Supabase Auth for sign-in and sign-up.
- App shell → Auth state: session state · Top-level app state depends on the auth hook.
- Dashboard → Bookmarks state: data state · Dashboard consumes cached bookmark queries and mutations.
- Dashboard → Bookmark UI: composes · Dashboard assembles bookmark cards, modals, filters, and tag input.
- Dashboard → Layout UI: uses shell · Dashboard uses header and sidebar layout pieces.
- Bookmarks state → API client: requests · Bookmarks hook fetches and mutates through the FastAPI client.
- API client → FastAPI app: Bearer JWT · Authenticated browser requests flow to the backend API.
- FastAPI app → Bookmark routes: mounts · Main app registers bookmark routes.
- FastAPI app → Tag routes: mounts · Main app registers tag routes.
- FastAPI app → Metadata route: mounts · Main app registers metadata routes.
- FastAPI app → Backend config: loads · Application startup reads central configuration.
- FastAPI app → Supabase backend: auth layer · Backend depends on server-side Supabase client and auth checks.
- Bookmark routes → Bookmark service: delegates · Route handlers delegate bookmark logic to the service layer.
- Bookmark routes → Bookmark schema: validates · Routes use Pydantic schemas for request and response shapes.
- Metadata route → Metadata service: delegates · Metadata endpoints offload fetch and parse logic to a service.
- Bookmark service → DB schema: persists to · Service reads and writes bookmark rows in Postgres via Supabase.
- Supabase client → DB schema: auth identity · Client-authenticated user identity is established through Supabase Auth.
- DB schema → Supabase backend: RLS checks · Database policies enforce ownership using JWT-derived identity.
- Shared types → Bookmark schema: mirrors · Frontend types mirror backend contract shapes.
- CI pipeline → Backend image: builds · CI checks backend container build integrity.
- CI pipeline → Frontend image: builds · CI checks frontend container build integrity.
- Compose setup → Frontend image: runs · Compose wires the frontend container into the local stack.
- Compose setup → Backend image: runs · Compose wires the backend container into the local stack.
- Dev compose → Frontend image: runs · Dev compose includes the frontend service.
- Dev compose → Backend image: runs · Dev compose includes the backend service.
