# guinea-cat/database-pj architecture

> Architecture diagram of the GitHub repository guinea-cat/database-pj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guinea-cat/database-pj
- Repository: https://github.com/guinea-cat/database-pj

## Overview

1. This is a three-part airline ticketing system: a MySQL database layer, a Spring Boot backend on port 8080, and a React + TypeScript frontend on port 5173. The backend is the main business engine; the frontend is a thin client that calls backend APIs.

2. The database folder is the source of truth for the domain model. `schema.sql` defines the airline-ticket schema, and `seed_data.sql` loads demo data. The README says the project is intentionally limited to 9 core tables, matching the ER design used in the course project.

3. Backend entry point is `AirticketApplication.java`. The backend is organized in a classic layered structure: controllers handle HTTP, services implement business rules, repositories access data, entities represent tables, and DTOs isolate request/response payloads.

4. The HTTP boundary is split by business capability rather than by generic CRUD. Main controllers are `AuthController`, `AdminController`, `TicketController`, `PassengerFlightController`, `MealController`, and `MemberController`, which suggests separate flows for login, administration, ticket operations, passenger-facing flight browsing, meal-related actions, and member account actions.

5. Business logic is concentrated in services: `AuthService`, `AdminService`, `TicketService`, `FlightSearchService`, and `ExpiredOrderService`. These services likely orchestrate validation, state transitions, pricing/discount logic, order creation, payment/refund/change flows, and admin maintenance operations.

6. Persistence is centered on domain repositories for `User`, `City`, `Airport`, `Aircraft`, `Flight`, `FlightSegment`, `MealOption`, `MealReservation`, and `TicketSale`. This shows the core data model spans reference data, flight structure, selling/orders, and optional meal reservations.

7. The domain layer uses enums to control business state: `CabinClass`, `FlightStatus`, `MemberLevel`, `TicketStatus`, and `UserType`. These enums are important architectural boundaries because they encode workflow and permissions, not just labels.

8. Several cross-cutting components shape runtime behavior. `GlobalExceptionHandler` and `BusinessException` provide centralized error handling; `ApiResponse` and `PageResult` standardize response payloads; `CorsConfig` enables frontend-to-backend access; `SecurityUtil` likely handles current-user context or auth helpers.

9. Order lifecycle is time-sensitive. `TicketExpireScheduler` and `ExpiredOrderService` indicate the backend runs a scheduled job to expire unpaid orders automatically, so ticket state is not purely request-driven.

10. Ticket and member flows appear to be the most stateful part of the system. The DTOs include create/pay/refund/change requests and responses such as `TicketResponse` and `AuthResponse`, which suggests the backend exposes explicit workflow endpoints rather than only CRUD on tickets.

11. The frontend is a Vite-based React app with TypeScript. `src/api/client.ts` and `src/api/airticket.ts` are the integration boundary to the backend, while `types.ts` and `lib/display.ts` show the UI is driven by typed backend data and display helpers.

12. Testing is present on both backend and frontend sides. Backend tests cover services and DTO behavior, while frontend tests cover the API client and display utilities, indicating the architecture relies on service-level correctness and frontend contract checks rather than heavy end-to-end automation.

13. Operationally, the system depends on MySQL plus standard Java/Node toolchains. The backend is packaged with Maven, and the frontend is developed with npm/Vite; the database scripts and documentation in `docs/` are part of the system design, not just auxiliary notes.

14. For an architecture diagram, the main data flow is: browser UI -> frontend API client -> backend controllers -> service layer -> repositories -> MySQL, with schedulers acting on the database in the background and exception/response wrappers shaping the API boundary.

Main entry points: [`backend/src/main/java/com/example/airticket/service`](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/service) (Services), [`backend/src/main/java/com/example/airticket/controller`](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/controller) (Controllers), [`database/schema.sql`](https://github.com/guinea-cat/database-pj/blob/main/database/schema.sql) (MySQL DB), [`frontend/src/api/client.ts`](https://github.com/guinea-cat/database-pj/blob/main/frontend/src/api/client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["React UI<br/>frontend app<br/>[App.tsx]"]
  node_api["API Client<br/>http client<br/>[client.ts]"]
  node_display["Display Utils<br/>ui helpers<br/>[display.ts]"]
end

subgraph group_backend["Backend"]
  node_app(("App Entry<br/>spring boot entry"))
  node_controllers["Controllers<br/>http boundary"]
  node_services["Services<br/>business layer"]
  node_repos["Repositories<br/>data access"]
  node_entities["Entities<br/>domain model"]
  node_dtos["DTOs<br/>api contracts"]
  node_enums{{"Enums<br/>workflow state"}}
  node_errors["Errors<br/>exception handling"]
  node_common["Responses<br/>payload wrappers"]
  node_security["Security Util<br/>auth helper<br/>[SecurityUtil.java]"]
  node_cors["CORS Config<br/>web config<br/>[CorsConfig.java]"]
end

subgraph group_data["Data"]
  node_db[("MySQL DB<br/>relational database<br/>[schema.sql]")]
  node_schema["Schema<br/>[schema.sql]"]
  node_seed["Seed Data<br/>sql seed<br/>[seed_data.sql]"]
end

subgraph group_ops["Runtime"]
  node_scheduler["Expiry Job<br/>scheduled task"]
end

node_app -->|"starts"| node_controllers
node_controllers -->|"delegates"| node_services
node_services -->|"queries"| node_repos
node_repos -->|"maps"| node_entities
node_entities -->|"stores"| node_db
node_schema -->|"defines"| node_db
node_seed -->|"loads"| node_db
node_controllers -->|"accepts/returns"| node_dtos
node_services -->|"uses"| node_dtos
node_services -->|"applies"| node_enums
node_services -->|"throws"| node_errors
node_errors -->|"formats"| node_common
node_controllers -->|"wraps"| node_common
node_services -->|"checks"| node_security
node_scheduler -->|"invokes"| node_services
node_scheduler -->|"updates"| node_db
node_ui -->|"calls"| node_api
node_api -->|"requests"| node_controllers
node_ui -->|"renders"| node_display
node_api -->|"crosses"| node_cors

click node_db "https://github.com/guinea-cat/database-pj/blob/main/database/schema.sql"
click node_schema "https://github.com/guinea-cat/database-pj/blob/main/database/schema.sql"
click node_seed "https://github.com/guinea-cat/database-pj/blob/main/database/seed_data.sql"
click node_app "https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/AirticketApplication.java"
click node_controllers "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/controller"
click node_services "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/service"
click node_repos "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/repository"
click node_entities "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/entity"
click node_dtos "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/dto"
click node_enums "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/enums"
click node_errors "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/exception"
click node_common "https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/common"
click node_security "https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/util/SecurityUtil.java"
click node_scheduler "https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/scheduler/TicketExpireScheduler.java"
click node_cors "https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/config/CorsConfig.java"
click node_ui "https://github.com/guinea-cat/database-pj/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/guinea-cat/database-pj/blob/main/frontend/src/api/client.ts"
click node_display "https://github.com/guinea-cat/database-pj/blob/main/frontend/src/lib/display.ts"

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_ui,node_api,node_display toneBlue
class node_app,node_controllers,node_services,node_repos,node_entities,node_dtos,node_enums,node_errors,node_common,node_security,node_cors toneAmber
class node_db,node_schema,node_seed toneMint
class node_scheduler toneRose
```

## Components

### Frontend

React + TypeScript client and API integration layer

- [React UI](https://github.com/guinea-cat/database-pj/blob/main/frontend/src/App.tsx): frontend app · Vite-based React and TypeScript client · `frontend/src/App.tsx`
- [API Client](https://github.com/guinea-cat/database-pj/blob/main/frontend/src/api/client.ts): http client · Frontend integration boundary to backend endpoints · `frontend/src/api/client.ts`
- [Display Utils](https://github.com/guinea-cat/database-pj/blob/main/frontend/src/lib/display.ts): ui helpers · Formatting and display helpers for backend-driven data · `frontend/src/lib/display.ts`

### Backend

Spring Boot business engine and layered API

- [App Entry](https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/AirticketApplication.java): spring boot entry · Backend application bootstrap · `backend/src/main/java/com/example/airticket/AirticketApplication.java`
- [Controllers](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/controller): http boundary · Capability-based REST endpoints for auth, admin, tickets, flights, meals, and members · `backend/src/main/java/com/example/airticket/controller`
- [Services](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/service): business layer · Business rules and orchestration for auth, admin, ticketing, flight search, and expiry · `backend/src/main/java/com/example/airticket/service`
- [Repositories](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/repository): data access · Persistence interfaces for core airline domain entities · `backend/src/main/java/com/example/airticket/repository`
- [Entities](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/entity): domain model · JPA entities mirroring airline tables and relationships · `backend/src/main/java/com/example/airticket/entity`
- [DTOs](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/dto): api contracts · Request and response payloads isolating API inputs and outputs · `backend/src/main/java/com/example/airticket/dto`
- [Enums](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/enums): workflow state · Cabin, flight, member, ticket, and user type state boundaries · `backend/src/main/java/com/example/airticket/enums`
- [Errors](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/exception): exception handling · Business exception and centralized API error mapping · `backend/src/main/java/com/example/airticket/exception`
- [Responses](https://github.com/guinea-cat/database-pj/tree/main/backend/src/main/java/com/example/airticket/common): payload wrappers · Standard API response and pagination wrappers · `backend/src/main/java/com/example/airticket/common`
- [Security Util](https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/util/SecurityUtil.java): auth helper · Current-user and security context helper functions · `backend/src/main/java/com/example/airticket/util/SecurityUtil.java`
- [CORS Config](https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/config/CorsConfig.java): web config · Cross-origin access from frontend to backend APIs · `backend/src/main/java/com/example/airticket/config/CorsConfig.java`

### Data

MySQL schema and seed data as the domain source of truth

- [MySQL DB](https://github.com/guinea-cat/database-pj/blob/main/database/schema.sql): relational database · Persisted airline domain data and demo seed content · `database/schema.sql`
- [Schema](https://github.com/guinea-cat/database-pj/blob/main/database/schema.sql): sql schema · Core airline ticket schema for the nine-table domain model · `database/schema.sql`
- [Seed Data](https://github.com/guinea-cat/database-pj/blob/main/database/seed_data.sql): sql seed · Demo records used to initialize the database · `database/seed_data.sql`

### Runtime

Cross-cutting runtime support and scheduled jobs

- [Expiry Job](https://github.com/guinea-cat/database-pj/blob/main/backend/src/main/java/com/example/airticket/scheduler/TicketExpireScheduler.java): scheduled task · Background job that expires unpaid orders · `backend/src/main/java/com/example/airticket/scheduler/TicketExpireScheduler.java`

## Connections

- App Entry → Controllers: starts · Bootstraps the HTTP API
- Controllers → Services: delegates · Routes capability-specific requests into business logic
- Services → Repositories: queries · Reads and writes persisted domain state
- Repositories → Entities: maps · Repository layer persists entity models
- Entities → MySQL DB: stores · Entity state is materialized in MySQL
- Schema → MySQL DB: defines · Schema establishes the core domain tables
- Seed Data → MySQL DB: loads · Demo data populates the database
- Controllers → DTOs: accepts/returns · HTTP endpoints use request and response DTOs
- Services → DTOs: uses · Service methods assemble and validate payloads
- Services → Enums: applies · Workflow and permission states constrain behavior
- Services → Errors: throws · Business failures are centralized as exceptions
- Errors → Responses: formats · Error handling produces standardized API responses
- Controllers → Responses: wraps · Responses are normalized for the frontend
- Services → Security Util: checks · Business logic can inspect current-user context
- Expiry Job → Services: invokes · Background expiry workflow reuses business logic
- Expiry Job → MySQL DB: updates · Expired orders are reconciled against persisted state
- React UI → API Client: calls · Browser UI talks through the frontend API client
- API Client → Controllers: requests · Frontend sends HTTP requests to backend endpoints
- React UI → Display Utils: renders · UI formatting uses shared display helpers
- API Client → CORS Config: crosses · Frontend access depends on CORS configuration