# whyeric92-eng/bookmark-api architecture

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

- Interactive diagram: https://gitdiagram.com/whyeric92-eng/bookmark-api
- Repository: https://github.com/whyeric92-eng/bookmark-api

## Overview

Bookmark API is a personal bookmark manager: users register or log in, then manage their own bookmarks and tags, search/filter bookmarks, and update their profile. The React app routes users through these workflows and sends authenticated requests to FastAPI; the backend validates identity and ownership before route handlers use SQLModel sessions and relational models. The README documents PostgreSQL persistence and stateless JWT logout. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README; sampled code does not expose every frontend request or database interaction.

Main entry points: [`app/db/session.py`](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/db/session.py) (Database session), [`frontend/src/App.jsx`](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/App.jsx) (Client routes), [`frontend/src/api.js`](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/api.js) (API client), [`app/api/router.py`](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/router.py) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_app_routes["Client routes<br/>[App.jsx]"]
  node_auth_pages["Register and login<br/>[Register.jsx]"]
  node_bookmark_page["Bookmark workspace<br/>[Bookmarks.jsx]"]
  node_tag_page["Tag workspace<br/>[Tags.jsx]"]
  node_profile_page["Profile<br/>[Profile.jsx]"]
  node_nav["Navigation and logout<br/>[NavBar.jsx]"]
  node_confirm["Confirmation modal<br/>[ConfirmModal.jsx]"]
  node_http_client["API client<br/>[api.js]"]
end

subgraph group_api["FastAPI API"]
  node_api_router["API router<br/>[router.py]"]
  node_user_routes["User endpoints<br/>[users.py]"]
  node_bookmark_routes["Bookmark endpoints<br/>[bookmarks.py]"]
  node_tag_routes["Tag endpoints<br/>[tags.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth_access["Token and ownership checks<br/>[deps.py]"]
  node_security["JWT and password security<br/>[security.py]"]
end

subgraph group_data["Persistence model"]
  node_session["Database session<br/>[session.py]"]
  node_user_model[("User model<br/>[user.py]")]
  node_bookmark_model[("Bookmark model<br/>[bookmark.py]")]
  node_tag_model[("Tag and link model<br/>[tag.py]")]
end

node_user(("User"))

node_user -->|"uses app"| node_app_routes
node_app_routes -->|"routes to"| node_auth_pages
node_app_routes -->|"routes to"| node_bookmark_page
node_app_routes -->|"routes to"| node_tag_page
node_app_routes -->|"routes to"| node_profile_page
node_bookmark_page -->|"calls"| node_http_client
node_tag_page -->|"calls"| node_http_client
node_profile_page -->|"calls"| node_http_client
node_auth_pages -->|"calls"| node_http_client
node_bookmark_page -->|"renders"| node_nav
node_tag_page -->|"renders"| node_nav
node_profile_page -->|"renders"| node_nav
node_nav -->|"renders"| node_confirm
node_http_client -.->|"sends requests"| node_api_router
node_api_router -->|"registers"| node_bookmark_routes
node_api_router -->|"registers"| node_tag_routes
node_api_router -->|"registers"| node_user_routes
node_user_routes -->|"hashes and issues tokens"| node_security
node_auth_access -->|"decodes tokens"| node_security
node_auth_access -->|"loads resources"| node_session
node_bookmark_routes -->|"requires ownership"| node_auth_access
node_tag_routes -->|"requires ownership"| node_auth_access
node_user_routes -->|"uses session"| node_session
node_bookmark_routes -->|"queries and commits"| node_session
node_tag_routes -->|"queries and commits"| node_session
node_session -.->|"persists"| node_bookmark_model
node_session -.->|"persists"| node_tag_model
node_session -.->|"persists"| node_user_model
node_bookmark_model -->|"many-to-many link"| node_tag_model
node_user_model -->|"owns bookmarks"| node_bookmark_model
node_user_model -->|"owns tags"| node_tag_model

click node_app_routes "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/App.jsx"
click node_auth_pages "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Register.jsx"
click node_bookmark_page "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Bookmarks.jsx"
click node_tag_page "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Tags.jsx"
click node_profile_page "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Profile.jsx"
click node_nav "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/components/NavBar.jsx"
click node_confirm "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/components/ConfirmModal.jsx"
click node_http_client "https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/api.js"
click node_api_router "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/router.py"
click node_user_routes "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/users.py"
click node_bookmark_routes "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/bookmarks.py"
click node_tag_routes "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/tags.py"
click node_auth_access "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/deps.py"
click node_security "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/core/security.py"
click node_session "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/db/session.py"
click node_user_model "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/user.py"
click node_bookmark_model "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/bookmark.py"
click node_tag_model "https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/tag.py"

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_app_routes,node_auth_pages,node_bookmark_page,node_tag_page,node_profile_page,node_nav,node_confirm,node_http_client,node_user toneBlue
class node_api_router,node_user_routes,node_bookmark_routes,node_tag_routes toneAmber
class node_auth_access,node_security toneMint
class node_session,node_user_model,node_bookmark_model,node_tag_model toneRose
```

## Components

### React client

- [Client routes](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Register and login](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Register.jsx): `frontend/src/pages/Register.jsx`
- [Bookmark workspace](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Bookmarks.jsx): `frontend/src/pages/Bookmarks.jsx`
- [Tag workspace](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Tags.jsx): `frontend/src/pages/Tags.jsx`
- [Profile](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/pages/Profile.jsx): `frontend/src/pages/Profile.jsx`
- [Navigation and logout](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/components/NavBar.jsx): `frontend/src/components/NavBar.jsx`
- [Confirmation modal](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/components/ConfirmModal.jsx): `frontend/src/components/ConfirmModal.jsx`
- [API client](https://github.com/whyeric92-eng/bookmark-api/blob/main/frontend/src/api.js): `frontend/src/api.js`

### FastAPI API

- [API router](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/router.py): `app/api/router.py`
- [User endpoints](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/users.py): `app/api/routes/users.py`
- [Bookmark endpoints](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/bookmarks.py): `app/api/routes/bookmarks.py`
- [Tag endpoints](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/routes/tags.py): `app/api/routes/tags.py`

### Identity and access

- [Token and ownership checks](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/api/deps.py): `app/api/deps.py`
- [JWT and password security](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/core/security.py): `app/core/security.py`

### Persistence model

- [Database session](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/db/session.py): `app/db/session.py`
- [User model](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/user.py): `app/models/user.py`
- [Bookmark model](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/bookmark.py): `app/models/bookmark.py`
- [Tag and link model](https://github.com/whyeric92-eng/bookmark-api/blob/main/app/models/tag.py): `app/models/tag.py`

### Other components

- **User**

## Connections

- User → Client routes: uses app (evidence: `frontend/src/App.jsx`)
- Client routes → Register and login: routes to (evidence: `frontend/src/App.jsx`)
- Client routes → Bookmark workspace: routes to (evidence: `frontend/src/App.jsx`)
- Client routes → Tag workspace: routes to (evidence: `frontend/src/App.jsx`)
- Client routes → Profile: routes to (evidence: `frontend/src/App.jsx`)
- Bookmark workspace → API client: calls (evidence: `frontend/src/pages/Bookmarks.jsx`)
- Tag workspace → API client: calls (evidence: `frontend/src/pages/Tags.jsx`)
- Profile → API client: calls (evidence: `frontend/src/pages/Profile.jsx`)
- Register and login → API client: calls (evidence: `frontend/src/pages/Register.jsx`)
- Bookmark workspace → Navigation and logout: renders (evidence: `frontend/src/pages/Bookmarks.jsx`)
- Tag workspace → Navigation and logout: renders (evidence: `frontend/src/pages/Tags.jsx`)
- Profile → Navigation and logout: renders (evidence: `frontend/src/pages/Profile.jsx`)
- Navigation and logout → Confirmation modal: renders (evidence: `frontend/src/components/NavBar.jsx`)
- API client → API router: sends requests
- API router → Bookmark endpoints: registers (evidence: `app/api/router.py`)
- API router → Tag endpoints: registers (evidence: `app/api/router.py`)
- API router → User endpoints: registers (evidence: `app/api/router.py`)
- User endpoints → JWT and password security: hashes and issues tokens (evidence: `app/api/routes/users.py`)
- Token and ownership checks → JWT and password security: decodes tokens (evidence: `app/api/deps.py`)
- Token and ownership checks → Database session: loads resources (evidence: `app/api/deps.py`)
- Bookmark endpoints → Token and ownership checks: requires ownership (evidence: `app/api/routes/bookmarks.py`)
- Tag endpoints → Token and ownership checks: requires ownership (evidence: `app/api/routes/tags.py`)
- User endpoints → Database session: uses session (evidence: `app/api/routes/users.py`)
- Bookmark endpoints → Database session: queries and commits (evidence: `app/api/routes/bookmarks.py`)
- Tag endpoints → Database session: queries and commits (evidence: `app/api/routes/tags.py`)
- Database session → Bookmark model: persists
- Database session → Tag and link model: persists
- Database session → User model: persists
- Bookmark model → Tag and link model: many-to-many link (evidence: `app/models/bookmark.py`)
- User model → Bookmark model: owns bookmarks (evidence: `app/models/user.py`)
- User model → Tag and link model: owns tags (evidence: `app/models/user.py`)
