How alonsodelrio/bookmark-manager works
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: main.py FastAPI app · DashboardPage.tsx Dashboard · App.tsx App shell · bookmarks.py Bookmark routes
Components 25
Frontend
React UI, client state, and browser-side API/auth integration.
- App shell · Wires providers and page-level app composition.
frontend/src/App.tsx - Auth page · Sign-in and sign-up experience.
frontend/src/pages/AuthPage.tsx - Dashboard · Main bookmark workspace and page composition.
frontend/src/pages/DashboardPage.tsx - Bookmark UI · Bookmark cards, modals, filters, and tag input.
frontend/src/components/bookmarks - Layout UI · Header and sidebar shell for the dashboard.
frontend/src/components/layout - Auth state · Tracks Supabase session and auth state across the app.
frontend/src/hooks/useAuth.tsx - Bookmarks state · Server state, caching, mutations, and optimistic updates for bookmarks.
frontend/src/hooks/useBookmarks.ts - API client · Calls FastAPI and injects the user JWT as Bearer auth.
frontend/src/lib/api.ts - Supabase client · Browser-side Supabase Auth integration for sign-in, sign-up, and sign-out.
frontend/src/lib/supabase.ts - Shared types · Frontend data contracts mirrored from backend schemas.
frontend/src/types/index.ts
Backend
FastAPI routes, services, and server-side auth/validation.
- FastAPI app · Application wiring and router registration.
backend/app/main.py - Backend config · Centralized settings and environment configuration.
backend/app/core/config.py - Supabase backend · Server-side Supabase client and auth dependencies.
backend/app/core/supabase.py - Bookmark routes · CRUD and ownership-aware bookmark endpoints.
backend/app/routers/bookmarks.py - Tag routes · Tag-related bookmark operations and filtering support.
backend/app/routers/tags.py - Metadata route · Server-side URL fetch and metadata extraction endpoints.
backend/app/routers/metadata.py - Bookmark service · Business logic for bookmark validation and persistence.
backend/app/services/bookmark.py - Metadata service · Fetches pages and extracts title/favicon metadata with fallbacks.
backend/app/services/metadata.py - Bookmark schema · Backend request/response shapes for bookmark data.
backend/app/schemas/bookmark.py
Supabase
Managed Auth and Postgres layer with row-level security.
- DB schema · Bookmarks table and row-level security policies.
supabase/schema.sql
Infra
Containerization, CI, and deployment wiring.
- CI pipeline · Runs backend lint/tests, frontend checks, and Docker smoke builds.
.github/workflows/ci.yml - Compose setup · Local multi-service startup for frontend, backend, and Supabase dependencies.
docker-compose.yml - Dev compose · Development-oriented container composition.
docker-compose.dev.yml - Frontend image · Builds the React app and serves it with Nginx.
frontend/Dockerfile - Backend image · Packages and runs the FastAPI service.
backend/Dockerfile
Connections 27
- 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.