# spring-petclinic/spring-petclinic-graphql architecture

> Architecture diagram of the GitHub repository spring-petclinic/spring-petclinic-graphql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spring-petclinic/spring-petclinic-graphql
- Repository: https://github.com/spring-petclinic/spring-petclinic-graphql

## Overview

##### Project type and purpose
- This is a full-stack sample application (“PetClinic”) demonstrating a GraphQL API built with Spring Boot/Spring for GraphQL (backend module), a React/Apollo single-page app frontend (frontend module), and a customized GraphiQL client (petclinic-graphiql module). It also includes end-to-end tests (e2e-tests) and Docker/Docker-Compose configurations for local and production-like deployments.

##### File structure
- Top-level modules:
- backend – Spring Boot GraphQL service (Java/Maven)
- frontend – React + Apollo GraphQL client (TypeScript/pnpm/Vite)
- petclinic-graphiql – standalone GraphiQL UI with login (TypeScript/pnpm/Vite)
- e2e-tests – Playwright tests against running containers
- docker-compose*.yml, build scripts, GitHub workflows
- backend uses layered packages: graphql controllers, model, repository, security, util, runtime wiring.
- Configuration files: application.properties, GraphQL schema, Flyway migrations, JWT key pair.
- Frontend uses GraphQL codegen, Apollo client setup, login flow, GraphQL queries & subscriptions.
- Deployment: Dockerfiles for frontend and backend, nginx proxy in docker-compose-petclinic.yml.

##### README for additional insights
- GraphQL API endpoints (HTTP /graphql and WebSocket /graphqlws) secured by JWT.
- Features: annotated controllers, custom scalars, paging/filtering, subscriptions, @PreAuthorize methods, testcontainers integration.
- Development vs “production” setup: local dev uses Vite dev server with proxy, production uses nginx reverse proxy.

a. Main components
- PostgreSQL database (Flyway migrations)
- Spring Boot GraphQL server
– GraphQL HTTP endpoint
– GraphQL WebSocket endpoint
– Security: JWT issuance & validation
– Service layer (PetService, OwnerService, VetService, VisitService)
– Repository layer (Spring Data JPA)
– GraphQL controllers/resolvers (AuthController, OwnerController, VisitController, etc.)
- React SPA frontend (frontend)
– Apollo Client (queries, mutations, subscriptions)
– UI components, login flow (AuthTokenProvider)
- Custom GraphiQL client (petclinic-graphiql)
- Reverse proxy / CDN (nginx in production)
- CI/CD & container orchestration
– GitHub Actions building images, running tests
– Docker-Compose for multi-container setup
- E2E test runner (Playwright)

b. Relationships & interactions
- SPA & GraphiQL → HTTP POST /graphql (queries, mutations)
- SPA → WebSocket /graphqlws (subscriptions)
- GraphQL server → database via JPA repositories
- Client login → /login endpoint → JWT token → stored in browser → attached to GraphQL calls
- nginx (prod) or Vite proxy (dev) → routes /graphql, /api to backend
- CI pipeline triggers build → spin up containers → run e2e tests

c. Architectural patterns & principles
- Layered architecture: controllers → services → repositories
- GraphQL schema-first with runtime wiring (scalars, interfaces, unions)
- Event-driven subscriptions (VisitPublisher)
- Security by design: JWT, method-level @PreAuthorize checks
- Paging/Filtering via Relay cursor connections
- Dev/prod parity with Docker Compose

d. Key technologies & frameworks
- Java 17, Spring Boot 3.x, Spring for GraphQL
- Flyway for DB migrations
- PostgreSQL
- React, TypeScript, Apollo Client, Vite
- GraphiQL (custom build)
- Playwright for E2E
- Docker, Docker Compose, nginx
- GitHub Actions

##### Detail
- Subscription path (VisitController → VisitPublisher → WS).
- JWT login flow (LoginController → JwtTokenService → key store).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        SPA["React SPA (React, Apollo)"]:::frontend
        GraphiQLClient["Custom GraphiQL Client"]:::frontend
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        direction TB
        ViteProxy["Vite Dev Proxy<br>/graphql → backend:3080"]:::infra
        NGINX["nginx Reverse Proxy<br>/graphql, /api → backend"]:::infra
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["Spring Boot GraphQL Server"]:::api
        subgraph "Controllers & Resolvers"
            Controllers["GraphQL Controllers"]:::api
        end
        subgraph "Security"
            Sec["JWT Issuance & Validation"]:::api
        end
        subgraph "Business Logic"
            Serv["Service Layer"]:::api
        end
        subgraph "Data Access"
            Repo["Repository Layer (JPA)"]:::api
        end
        subgraph "Schema"
            SchemaDef["GraphQL Schema (.graphqls)"]:::api
            RuntimeWiring["Runtime Wiring"]:::api
        end
        subgraph "UI Assets"
            CIUI["Embedded GraphiQL UI"]:::api
        end
    end

    %% Data Layer
    DB["PostgreSQL Database"]:::db

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        direction TB
        GH["GitHub Actions"]:::ci
        ComposeLocal["Docker Compose (dev)"]:::infra
        ComposeProd["Docker Compose (prod)"]:::infra
        E2EWorkflow["Playwright Workflow"]:::ci
        E2ETests["Playwright E2E Tests"]:::test
    end

    %% Connections
    SPA -->|HTTP POST /graphql / WS| ViteProxy
    SPA -->|HTTP POST /graphql / WS| NGINX
    GraphiQLClient -->|HTTP POST /graphql| ViteProxy
    GraphiQLClient -->|HTTP POST /graphql| NGINX

    ViteProxy -->|Forward| API
    NGINX -->|Forward| API

    API -->|JPA| Repo
    Repo -->|SQL| DB
    API -->|Service Calls| Serv
    Serv -->|Repo Access| Repo
    API -->|Controllers invoke| Controllers
    Controllers -->|Auth| Sec
    Controllers -->|Schema| SchemaDef
    Controllers -->|Runtime| RuntimeWiring
    API -->|Serves UI| CIUI

    GH -->|Build & Push| ComposeLocal
    GH -->|Build & Push| ComposeProd
    ComposeLocal -->|Start Containers| API
    ComposeLocal -->|Start Containers| DB
    ComposeLocal -->|Start Containers| NGINX
    ComposeProd -->|Start Containers| API
    ComposeProd -->|Start Containers| DB
    ComposeProd -->|Start Containers| NGINX
    ComposeLocal -->|Trigger| E2ETests
    E2EWorkflow -->|Run| E2ETests

    %% Click Events
    click DB "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/backend/src/main/resources/db/migration"
    click API "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/backend/src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java"
    click Controllers "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/backend/src/main/java/org/springframework/samples/petclinic/graphql/*Controller.java"
    click Sec "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/backend/src/main/java/org/springframework/samples/petclinic/security"
    click Serv "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/backend/src/main/java/org/springframework/samples/petclinic/model/*Service.java"
    click Repo "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/backend/src/main/java/org/springframework/samples/petclinic/repository/*.java"
    click SchemaDef "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/backend/src/main/resources/graphql/petclinic.graphqls"
    click RuntimeWiring "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/backend/src/main/java/org/springframework/samples/petclinic/graphql/runtime"
    click CIUI "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/backend/src/main/resources/ui/graphiql"
    click SPA "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/frontend/src"
    click SPA "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/frontend/src/create-graphql-client.ts"
    click SPA "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/frontend/src/login/AuthTokenProvider.tsx"
    click GraphiQLClient "https://github.com/spring-petclinic/spring-petclinic-graphql/tree/main/petclinic-graphiql/src"
    click NGINX "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/frontend/docker/nginx.conf"
    click ComposeLocal "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/docker-compose.yml"
    click ComposeProd "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/docker-compose-petclinic.yml"
    click GH "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/ .github/workflows/build-app.yml"
    click E2EWorkflow "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/e2e-tests/.github/workflows/playwright.yml"
    click E2ETests "https://github.com/spring-petclinic/spring-petclinic-graphql/blob/main/e2e-tests/tests/*.spec.ts"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px
    classDef api fill:#D5F5E3,stroke:#145A32,stroke-width:2px
    classDef db fill:#FCF3CF,stroke:#7D6608,stroke-width:2px
    classDef infra fill:#FADBD8,stroke:#7B241C,stroke-width:2px
    classDef ci fill:#E8DAEF,stroke:#6C3483,stroke-width:2px
    classDef test fill:#FDEBD0,stroke:#AF601A,stroke-width:2px
```
