# theunknownodysseus/pageturner architecture

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

- Interactive diagram: https://gitdiagram.com/theunknownodysseus/pageturner
- Repository: https://github.com/theunknownodysseus/pageturner

## Overview

##### What this project is (type + purpose)
From the file tree, this is a **full-stack web application** named **“pageturner”** with:
- A **Java Spring Boot backend** in `/bookmarks` (Maven project).
- A **React SPA frontend** in `/frontend` (Vite-based).

Domain-wise, the backend models a small shop-like system around:
- **Bookmarks** (`model/Bookmark.java`)
- **Orders** (`model/Order.java`)

The backend exposes functionality via controllers:
- `BookmarkController`
- `OrderController`

…and persists via repositories:
- `BookmarkRepository`
- `OrderRepository`

##### Backend (`/bookmarks`)
Key structure indicates classic Spring layering:
- `BookmarksApplication.java`: Spring Boot entrypoint.
- `controller/`: HTTP API boundary (REST endpoints).
- `service/`: business logic layer (notably `OrderService` exists; bookmark logic may be directly in controller or omitted).
- `repository/`: persistence abstraction (likely Spring Data JPA repositories).
- `model/`: domain entities (`Bookmark`, `Order`).

##### Frontend (`/frontend`)
A Vite React SPA:
- `src/pages/`: route-level pages (`Home.jsx`, `Order.jsx`).
- `src/components/`: presentational / UI components (`BookmarkCard`, `Navbar`, etc.).
- `App.jsx`, `main.jsx`: app bootstrap + routing composition.

This suggests browser-based rendering with API calls from pages (likely Home fetches bookmarks; Order posts/reads orders).

##### System Context (Level 1)
Include:
- **User** (Customer)
- **Web Browser**

If there are external services (none visible in tree), omit them to avoid speculation.

Containers distinctly:

##### Frontend Container
- “React SPA (Vite)” running in the user’s browser
- Key UI modules: Home page, Order page, shared components

##### Backend Container
- “Spring Boot API (Maven)” running as a server process
- Exposes REST endpoints via controllers

##### Database Container
- Not explicitly in tree, but clearly implied by repositories + entities + application.properties.

- Browser → React SPA: loads static assets (HTML/JS/CSS)
- React SPA → Spring Boot API: HTTP/JSON requests (REST)
- Spring Boot API → Database: CRUD via repositories/JPA

**Controllers (API layer)**
- `BookmarkController`
- `OrderController`

**Service (business layer)**
- `OrderService` (explicit)
- If bookmark-related service doesn’t exist, show BookmarkController calling repository directly (this is still “accurate to repo”).

**Persistence layer**
- `BookmarkRepository`
- `OrderRepository`

**Domain model**
- `Bookmark`
- `Order`

- `BookmarkController` → `BookmarkRepository` (or → BookmarkService if later added)
- `OrderController` → `OrderService` → `OrderRepository`
- Repositories → Database
- Controllers ↔ Domain models (request/response DTOs not shown in tree; if not present, don’t invent them—just show entities used in persistence)

- Pages: `Home`, `Order`
- Components: `BookmarkCard`, `Navbar`, `Footer`, etc.

- Either show **“Fetch/Axios calls inside pages”** (accurate)
- Or annotate “HTTP client calls (fetch) from pages to backend endpoints”

##### Architectural patterns to highlight (based on repo evidence)
- **Layered architecture** on backend: Controller → Service → Repository → DB
- **SPA frontend**: React component tree + pages
- **Spring Boot / Spring Data** conventions: repositories abstract DB access; models are entities
- **Separation of concerns**: UI in `/frontend`, API + persistence in `/bookmarks`

This yields accuracy without clutter.

##### Labels: be concrete and source-controlled
Prefer names that match the repo exactly:
- “OrderController”, “OrderService”, “OrderRepository”, etc.

- Protocol: **HTTP**
- Data: **JSON**

##### Boundaries explicitly
- “Browser”
- “Frontend (React/Vite)”
- “Backend (Spring Boot)”
- “Database”

This makes security/network boundaries clear (even if not yet deployed).

- **Build tools**
- Backend: Maven Wrapper (`mvnw`, `.mvn/`, `pom.xml`)
- Frontend: npm + Vite (`package.json`, `vite.config.js`)
- **Configuration**
- `application.properties` as “Backend config (DB, port, etc.)”
- **Tests**
- `BookmarksApplicationTests.java` as “Backend test suite (Spring Boot test)”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1: System Context
  %% =========================
  subgraph "System Context (Level 1)"
    U["Customer (User)"]:::external
    B["Web Browser"]:::external
    SYS["pageturner System"]:::system
    U -->|"uses"| B
    B -->|"accesses"| SYS
  end

  %% =========================
  %% Level 2: Container Diagram
  %% =========================
  subgraph "Container Diagram (Level 2)"
    direction TB

    subgraph "Client-Side"
      direction TB
      FE["React SPA (Vite)"]:::frontend
      FE_HTML["Static Assets (index.html / JS / CSS)"]:::artifact
      B -->|"loads"| FE_HTML
      FE_HTML -->|"bootstraps"| FE
    end

    subgraph "Server-Side"
      direction TB
      BE["Spring Boot REST API (Maven)"]:::backend
      CFG["Backend Config (application.properties)"]:::config
      DB[("Relational DB<br/>(via Spring Data JPA)")]:::database
      CFG -.->|"configures"| BE
      BE -->|"CRUD (JPA/SQL)"| DB
    end

    FE -->|"HTTP/JSON (REST)"| BE
  end

  %% =========================
  %% Level 3: Backend Components
  %% =========================
  subgraph "Backend Component Diagram (Level 3)"
    direction TB

    subgraph "Spring Boot API Internals"
      direction TB

      subgraph "Entrypoint"
        direction TB
        BE_APP["BookmarksApplication"]:::backend
      end

      subgraph "Controllers (REST API Layer)"
        direction TB
        BC["BookmarkController"]:::controller
        OC["OrderController"]:::controller
      end

      subgraph "Service (Business Layer)"
        direction TB
        OS["OrderService"]:::service
      end

      subgraph "Repositories (Persistence Layer)"
        direction TB
        BR["BookmarkRepository"]:::repository
        OR["OrderRepository"]:::repository
      end

      subgraph "Domain Models (Entities)"
        direction TB
        BM["Bookmark"]:::domain
        OM["Order"]:::domain
      end
    end

    %% Internal runtime flow
    BC -->|"uses (CRUD)"| BR
    OC -->|"delegates"| OS
    OS -->|"uses (CRUD)"| OR

    BR -->|"persists (JPA)"| DB
    OR -->|"persists (JPA)"| DB

    BC -.->|"reads/writes"| BM
    OC -.->|"reads/writes"| OM
    BR -.->|"maps entity"| BM
    OR -.->|"maps entity"| OM
  end

  %% =========================
  %% Level 3: Frontend Components
  %% =========================
  subgraph "Frontend Component Diagram (Level 3)"
    direction TB

    subgraph "React App Bootstrap"
      direction TB
      MAIN["main.jsx"]:::frontend
      APP["App.jsx (App Shell / Routing)"]:::frontend
      MAIN -->|"renders"| APP
    end

    subgraph "Pages (Route-level)"
      direction TB
      PAGES["pages/"]:::frontend
      HOME["Home.jsx"]:::page
      ORDER["Order.jsx"]:::page
      PAGES --> HOME
      PAGES --> ORDER
      APP -->|"routes"| HOME
      APP -->|"routes"| ORDER
    end

    subgraph "UI Components"
      direction TB
      COMPS["components/"]:::frontend
      NAV["Navbar.jsx"]:::component
      FOOT["Footer.jsx"]:::component
      CARD["BookmarkCard.jsx"]:::component
      VIS["BookmarkVisual.jsx"]:::component
      COMPS --> NAV
      COMPS --> FOOT
      COMPS --> CARD
      COMPS --> VIS
      HOME -->|"composes"| NAV
      HOME -->|"renders list"| CARD
      CARD -->|"uses"| VIS
      HOME -->|"composes"| FOOT
      ORDER -->|"composes"| NAV
      ORDER -->|"composes"| FOOT
    end

    %% API calls (no explicit api/ folder found)
    HOME -->|"fetch GET /bookmarks (example)"| BE
    ORDER -->|"fetch POST/GET /orders (example)"| BE
  end

  %% =========================
  %% Build / Tooling / Tests (Side Notes)
  %% =========================
  subgraph "Build, Tooling & Tests (Repo Evidence)"
    direction TB

    subgraph "Frontend Tooling"
      direction TB
      NPM["npm (package.json)"]:::tooling
      VITE["Vite Config (vite.config.js)"]:::tooling
      NPM -.->|"builds"| FE
      VITE -.->|"bundles"| FE
    end

    subgraph "Backend Tooling"
      direction TB
      POM["Maven (pom.xml)"]:::tooling
      MVNW["Maven Wrapper (mvnw)"]:::tooling
      MVNWCFG["maven-wrapper.properties"]:::tooling
      TESTS["BookmarksApplicationTests"]:::testing
      POM -.->|"builds"| BE
      MVNW -.->|"invokes Maven"| POM
      MVNWCFG -.->|"pins wrapper"| MVNW
      TESTS -.->|"tests"| BE
    end
  end

  %% =========================
  %% Click Events (Component Mapping)
  %% =========================
  click FE "https://github.com/theunknownodysseus/pageturner/tree/main/frontend/"
  click MAIN "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/main.jsx"
  click APP "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/App.jsx"
  click PAGES "https://github.com/theunknownodysseus/pageturner/tree/main/frontend/src/pages/"
  click HOME "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/pages/Home.jsx"
  click ORDER "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/pages/Order.jsx"
  click COMPS "https://github.com/theunknownodysseus/pageturner/tree/main/frontend/src/components/"
  click CARD "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/components/BookmarkCard.jsx"
  click VIS "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/components/BookmarkVisual.jsx"
  click NAV "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/components/Navbar.jsx"
  click FOOT "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/src/components/Footer.jsx"
  click BE "https://github.com/theunknownodysseus/pageturner/tree/main/bookmarks/"
  click BE_APP "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/BookmarksApplication.java"
  click CFG "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/resources/application.properties"
  click BC "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/controller/BookmarkController.java"
  click OC "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/controller/OrderController.java"
  click OS "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/service/OrderService.java"
  click BR "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/repository/BookmarkRepository.java"
  click OR "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/repository/OrderRepository.java"
  click BM "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/model/Bookmark.java"
  click OM "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/main/java/com/bookmarkshop/bookmarks/model/Order.java"
  click POM "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/pom.xml"
  click MVNW "https://github.com/theunknownodysseus/pageturner/tree/main/bookmarks/mvnw"
  click MVNWCFG "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/.mvn/wrapper/maven-wrapper.properties"
  click TESTS "https://github.com/theunknownodysseus/pageturner/blob/main/bookmarks/src/test/java/com/bookmarkshop/bookmarks/BookmarksApplicationTests.java"
  click NPM "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/package.json"
  click VITE "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/vite.config.js"
  click FE_HTML "https://github.com/theunknownodysseus/pageturner/blob/main/frontend/index.html"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#f5f7ff,stroke:#3b5bcc,stroke-width:1.5px,color:#0b1b4a
  classDef system fill:#e8f0ff,stroke:#2f4fd3,stroke-width:2px,color:#0b1b4a

  classDef frontend fill:#dff1ff,stroke:#1481c5,stroke-width:1.5px,color:#06324d
  classDef backend fill:#e9ecf2,stroke:#4b5563,stroke-width:1.5px,color:#111827
  classDef database fill:#fff0d9,stroke:#c97a12,stroke-width:1.5px,color:#4a2a00

  classDef controller fill:#f2f4f7,stroke:#6b7280,stroke-width:1.5px,color:#111827
  classDef service fill:#eef2ff,stroke:#4f46e5,stroke-width:1.5px,color:#111827
  classDef repository fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#111827
  classDef domain fill:#e8ffe9,stroke:#16a34a,stroke-width:1.5px,color:#052e12

  classDef tooling fill:#fff1f2,stroke:#be123c,stroke-width:1.5px,color:#4a0b18
  classDef config fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#06324d
  classDef testing fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.5px,color:#1f1147
  classDef page fill:#cfe9ff,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b4a
  classDef component fill:#bfe3ff,stroke:#1e40af,stroke-width:1.5px,color:#0b1b4a
  classDef artifact fill:#ffffff,stroke:#94a3b8,stroke-width:1.2px,color:#0f172a,stroke-dasharray: 4 3
```
