# cuongcon3010/field-booking architecture

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

- Interactive diagram: https://gitdiagram.com/cuongcon3010/field-booking
- Repository: https://github.com/cuongcon3010/field-booking

## Overview

Field Booking is a Google OAuth 2.0 sign-in service with a small Next.js interface and a Go/Gin backend. A visitor starts sign-in in the frontend; the backend protects the OAuth callback with state, exchanges the code with Google, creates or links an account, and returns an HttpOnly JWT cookie. The frontend then checks the session and can log out. The README documents account linking, verified-email checks, CORS, and PostgreSQL-backed user and OAuth-account records. Edges reflect shown calls and documented behavior; middleware validation details are not fully sampled.

Main entry points: [`BackEnd/internal/handler/auth_handler.go`](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/handler/auth_handler.go) (Auth endpoints), [`BackEnd/internal/service/auth_service.go`](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/service/auth_service.go) (Account resolution), [`BackEnd/cmd/server/main.go`](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/cmd/server/main.go) (Gin server), [`FrontEnd/app/page.tsx`](https://github.com/cuongcon3010/field-booking/blob/master/FrontEnd/app/page.tsx) (Sign-in page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_web["Sign-in page<br/>[page.tsx]"]
end

subgraph group_http["HTTP entry and security"]
  node_server["Gin server<br/>[main.go]"]
  node_handler["Auth endpoints<br/>[auth_handler.go]"]
  node_cors["CORS policy<br/>[cors_middleware.go]"]
  node_authmw["Session middleware<br/>[auth_middleware.go]"]
  node_config["Runtime config<br/>[config.go]"]
end

subgraph group_oauth["OAuth and identity"]
  node_google{{"Google OAuth"}}
  node_provider["OAuth provider<br/>[oauth_service.go]"]
end

subgraph group_identity["Account and session"]
  node_authservice["Account resolution<br/>[auth_service.go]"]
  node_tokens["JWT service<br/>[jwt.go]"]
end

subgraph group_persistence["Persistence"]
  node_users["User records<br/>[user.go]"]
  node_oauthaccounts["OAuth account records<br/>[oauth_account.go]"]
  node_userrepo["User repository<br/>[user_repository.go]"]
  node_oauthrepo["OAuth repository"]
  node_database[("PostgreSQL")]
  node_dbinit["Database setup<br/>[database.go]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_web
node_web -->|"starts login"| node_handler
node_web -->|"checks session"| node_handler
node_web -->|"requests logout"| node_handler
node_server -->|"loads"| node_config
node_server -->|"initializes"| node_dbinit
node_server -->|"registers routes"| node_handler
node_server -->|"installs"| node_cors
node_server -->|"guards session route"| node_authmw
node_handler -->|"exchanges code"| node_provider
node_provider -->|"requests identity"| node_google
node_google -->|"returns callback"| node_handler
node_handler -->|"resolves account"| node_authservice
node_authservice -->|"finds or saves user"| node_userrepo
node_authservice -->|"finds or links account"| node_oauthrepo
node_authservice -->|"generates token"| node_tokens
node_handler -->|"redirects after login"| node_web
node_userrepo -->|"reads and writes"| node_database
node_oauthrepo -->|"reads and writes"| node_database
node_dbinit -->|"connects and migrates"| node_database
node_dbinit -->|"migrates"| node_users
node_dbinit -->|"migrates"| node_oauthaccounts
node_authservice -->|"creates account data"| node_users
node_authservice -->|"creates link data"| node_oauthaccounts
node_authmw -.->|"validates token"| node_tokens

click node_web "https://github.com/cuongcon3010/field-booking/blob/master/FrontEnd/app/page.tsx"
click node_server "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/cmd/server/main.go"
click node_handler "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/handler/auth_handler.go"
click node_cors "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/middleware/cors_middleware.go"
click node_authmw "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/middleware/auth_middleware.go"
click node_config "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/config/config.go"
click node_provider "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/service/oauth_service.go"
click node_authservice "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/service/auth_service.go"
click node_tokens "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/pkg/jwt/jwt.go"
click node_users "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/model/user.go"
click node_oauthaccounts "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/model/oauth_account.go"
click node_userrepo "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/repository/user_repository.go"
click node_oauthrepo "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/repository/oauth_repository.go"
click node_dbinit "https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/database/database.go"

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_web toneBlue
class node_server,node_handler,node_cors,node_authmw,node_config toneAmber
class node_google,node_provider toneMint
class node_authservice,node_tokens toneRose
class node_users,node_oauthaccounts,node_userrepo,node_oauthrepo,node_database,node_dbinit,node_visitor toneIndigo
```

## Components

### Web interface

- [Sign-in page](https://github.com/cuongcon3010/field-booking/blob/master/FrontEnd/app/page.tsx): `FrontEnd/app/page.tsx`

### HTTP entry and security

- [Gin server](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/cmd/server/main.go): `BackEnd/cmd/server/main.go`
- [Auth endpoints](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/handler/auth_handler.go): `BackEnd/internal/handler/auth_handler.go`
- [CORS policy](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/middleware/cors_middleware.go): `BackEnd/internal/middleware/cors_middleware.go`
- [Session middleware](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/middleware/auth_middleware.go): `BackEnd/internal/middleware/auth_middleware.go`
- [Runtime config](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/config/config.go): `BackEnd/internal/config/config.go`

### OAuth and identity

- **Google OAuth**
- [OAuth provider](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/service/oauth_service.go): `BackEnd/internal/service/oauth_service.go`

### Account and session

- [Account resolution](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/service/auth_service.go): `BackEnd/internal/service/auth_service.go`
- [JWT service](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/pkg/jwt/jwt.go): `BackEnd/pkg/jwt/jwt.go`

### Persistence

- [User records](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/model/user.go): `BackEnd/internal/model/user.go`
- [OAuth account records](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/model/oauth_account.go): `BackEnd/internal/model/oauth_account.go`
- [User repository](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/repository/user_repository.go): `BackEnd/internal/repository/user_repository.go`
- [OAuth repository](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/repository/oauth_repository.go): `BackEnd/internal/repository/oauth_repository.go`
- **PostgreSQL**
- [Database setup](https://github.com/cuongcon3010/field-booking/blob/master/BackEnd/internal/database/database.go): `BackEnd/internal/database/database.go`

### Other components

- **Visitor**

## Connections

- Visitor → Sign-in page: opens (evidence: `FrontEnd/app/page.tsx`)
- Sign-in page → Auth endpoints: starts login (evidence: `FrontEnd/app/page.tsx`)
- Sign-in page → Auth endpoints: checks session (evidence: `FrontEnd/app/page.tsx`)
- Sign-in page → Auth endpoints: requests logout (evidence: `FrontEnd/app/page.tsx`)
- Gin server → Runtime config: loads (evidence: `BackEnd/cmd/server/main.go`)
- Gin server → Database setup: initializes (evidence: `BackEnd/cmd/server/main.go`)
- Gin server → Auth endpoints: registers routes (evidence: `BackEnd/cmd/server/main.go`)
- Gin server → CORS policy: installs (evidence: `BackEnd/cmd/server/main.go`)
- Gin server → Session middleware: guards session route (evidence: `BackEnd/cmd/server/main.go`)
- Auth endpoints → OAuth provider: exchanges code (evidence: `BackEnd/internal/handler/auth_handler.go`)
- OAuth provider → Google OAuth: requests identity (evidence: `BackEnd/internal/service/oauth_service.go`)
- Google OAuth → Auth endpoints: returns callback (evidence: `README.md`)
- Auth endpoints → Account resolution: resolves account (evidence: `BackEnd/internal/handler/auth_handler.go`)
- Account resolution → User repository: finds or saves user (evidence: `BackEnd/internal/service/auth_service.go`)
- Account resolution → OAuth repository: finds or links account (evidence: `BackEnd/internal/service/auth_service.go`)
- Account resolution → JWT service: generates token (evidence: `BackEnd/internal/service/auth_service.go`)
- Auth endpoints → Sign-in page: redirects after login (evidence: `BackEnd/internal/handler/auth_handler.go`)
- User repository → PostgreSQL: reads and writes (evidence: `BackEnd/internal/repository/user_repository.go`)
- OAuth repository → PostgreSQL: reads and writes (evidence: `BackEnd/internal/repository/oauth_repository.go`)
- Database setup → PostgreSQL: connects and migrates (evidence: `BackEnd/internal/database/database.go`)
- Database setup → User records: migrates (evidence: `BackEnd/internal/database/database.go`)
- Database setup → OAuth account records: migrates (evidence: `BackEnd/internal/database/database.go`)
- Account resolution → User records: creates account data (evidence: `BackEnd/internal/service/auth_service.go`)
- Account resolution → OAuth account records: creates link data (evidence: `BackEnd/internal/service/auth_service.go`)
- Session middleware → JWT service: validates token
