# nageoffer/12306 architecture

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

- Interactive diagram: https://gitdiagram.com/nageoffer/12306
- Repository: https://github.com/nageoffer/12306

## Overview

#### Purpose and deployment modes
A JDK 17, Spring Boot 3/Spring Cloud railway-ticketing system covering identity, passengers, ticket search/purchase, orders, payment, refunds, and gateway access. Maven is the backend build root (`pom.xml`). It supports:
- Microservices: independently run gateway, user, ticket, order, and payment applications under `services/`.
- Aggregated deployment/demo mode: run aggregation plus gateway via `services/aggregation-service/src/main/java/org/opengoofy/index12306/biz/aggregationservice/AggregationServiceApplication.java` and `services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java`.

A Vue console is a separate SPA entry point at `console-vue/src/main.js`, with routes and HTTP access in `console-vue/src/router/index.js` and `console-vue/src/service/axios.js`.

#### Edge, identity, and user domain
The gateway is the public request boundary, routing requests and validating JWTs before downstream services. `TokenValidateGatewayFilterFactory` extracts/validates user context; the shared user starter can propagate it between services.
- `services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/filter/TokenValidateGatewayFilterFactory.java`
- `frameworks/bizs/user/src/main/java/org/opengoofy/index12306/frameworks/starter/user/core/UserTransmitFilter.java`
- `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java`

User service owns registration, login, profile, and passenger records. Registration uses a responsibility chain and a Redis-backed Bloom-filter configuration to protect high-volume username checks.
- `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/service/handler/filter/user/UserRegisterCreateChainFilter.java`
- `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/config/RBloomFilterConfiguration.java`
- `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/PassengerController.java`

#### Ticket inventory and purchase orchestration
Ticket service owns train, station, carriage, seat, fare, and availability data, and exposes query and purchase APIs. Purchase first runs validation/stock/repeat-request chain stages, then selects a seat-class strategy/template and allocates physical seats. Availability is protected by a Redis/Lua token bucket with explicit rollback.
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java`
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/filter/purchase/TrainPurchaseTicketChainFilter.java`
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/tokenbucket/TicketAvailabilityTokenBucket.java`

Purchase crosses service boundaries: ticket service calls user data, creates an order remotely, and obtains payment information. It also consumes delayed-close and payment-result events to restore or finalize inventory.
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/remote/TicketOrderRemoteService.java`
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/mq/consumer/DelayCloseOrderConsumer.java`

#### Orders, payment, and asynchronous lifecycle
Order service persists orders, items, and passenger relations; it provides creation, cancellation, detail, and paginated query APIs. It publishes delayed order-close events and consumes payment/refund callbacks to advance order state.
- `services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/controller/TicketOrderController.java`
- `services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/mq/produce/DelayCloseOrderSendProduce.java`
- `services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/mq/consumer/PayResultCallbackOrderConsumer.java`

Payment service is the external payment boundary: it creates payments/refunds, handles provider callbacks, and emits RocketMQ result events for order reconciliation. The concrete provider integration is Alipay.
- `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java`
- `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/handler/AliPayNativeHandler.java`
- `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/mq/produce/PayResultCallbackOrderSendProduce.java`

#### Persistence, cache, and consistency infrastructure
Each bounded service owns DAOs/entities and uses MyBatis-Plus plus ShardingSphere configurations; order, pay, and user services define domain-specific database/table sharding algorithms. SQL bootstrap schemas are supplied under `resources/db/`.
- `services/order-service/src/main/resources/shardingsphere-config.yaml`
- `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/dao/algorithm/PayTableComplexAlgorithm.java`
- `resources/db/12306-springcloud-ticket.sql`

Redis supports distributed cache, multistage cache, Lua atomic operations, Bloom filters, distributed-ID worker allocation, and ticket tokens. RocketMQ carries delayed closure and payment/refund outcomes. Canal/binlog consumers update ticket cache/token state after database changes.
- `frameworks/cache/src/main/java/org/opengoofy/index12306/framework/starter/cache/MultistageCache.java`
- `frameworks/distributedid/src/main/java/org/opengoofy/index12306/framework/starter/distributedid/core/snowflake/LocalRedisWorkIdChoose.java`
- `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/canal/TicketAvailabilityCacheUpdateHandler.java`

#### Shared platform conventions
`frameworks/` is an internal Spring Boot starter layer, not business ownership: it standardizes result/error handling, web exception handling, authentication context, caching, IDs, idempotency, logging, database metadata, and reusable chain/strategy/template patterns. Auto-configurations are registered through Spring Boot imports.
- `frameworks/web/src/main/java/org/opengoofy/index12306/framework/starter/web/GlobalExceptionHandler.java`
- `frameworks/idempotent/src/main/java/org/opengoofy/index12306/framework/starter/idempotent/core/IdempotentAspect.java`
- `frameworks/designpattern/src/main/java/org/opengoofy/index12306/framework/starter/designpattern/chain/AbstractChainContext.java`

Main entry points: [`services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java`](https://github.com/nageoffer/12306/blob/main/services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java) (API Gateway), [`services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java`](https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java) (Ticket service), [`services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java`](https://github.com/nageoffer/12306/blob/main/services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java) (Payment service), [`services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java`](https://github.com/nageoffer/12306/blob/main/services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_console["Vue Console<br/>SPA<br/>[main.js]"]
end

subgraph group_services["Business services"]
  node_gateway{{"API Gateway<br/>Spring Cloud gateway"}}
  node_gateway_auth["JWT filter<br/>gateway filter"]
  node_aggregation["Aggregation service<br/>Spring Boot app"]
  node_user["User service<br/>identity domain"]
  node_user_registration["Registration guard<br/>chain + Bloom filter"]
  node_ticket["Ticket service<br/>inventory domain"]
  node_purchase["Purchase allocator<br/>purchase chain"]
  node_token_bucket["Availability token bucket<br/>Redis/Lua inventory"]
  node_order["Order service<br/>order domain"]
  node_payment["Payment service<br/>payment boundary"]
  node_alipay["Alipay<br/>payment provider"]
end

subgraph group_platform["Shared platform"]
  node_user_context["User context propagation<br/>shared starter"]
  node_platform_patterns["Platform patterns<br/>shared starters"]
end

subgraph group_infrastructure["Data and messaging"]
  node_redis[("Redis<br/>cache and coordination")]
  node_rocketmq["RocketMQ<br/>event bus"]
  node_sharded_db[("Sharded databases<br/>MyBatis-Plus + ShardingSphere")]
  node_canal["Canal cache updater<br/>binlog consumer"]
end

node_console -->|"HTTP API"| node_gateway
node_gateway -->|"validates JWT"| node_gateway_auth
node_gateway_auth -->|"establishes context"| node_user_context
node_gateway -.->|"aggregated mode"| node_aggregation
node_gateway -->|"routes identity APIs"| node_user
node_gateway -->|"routes ticket APIs"| node_ticket
node_gateway -->|"routes order APIs"| node_order
node_gateway -->|"routes payment APIs"| node_payment
node_user -->|"registration flow"| node_user_registration
node_user_registration -->|"username Bloom filter"| node_redis
node_ticket -->|"purchase request"| node_purchase
node_purchase -->|"reserve availability"| node_token_bucket
node_token_bucket -->|"atomic Lua tokens"| node_redis
node_ticket -->|"reads passenger data"| node_user
node_ticket -->|"creates order remotely"| node_order
node_order -->|"delayed close event"| node_rocketmq
node_payment -->|"provider integration"| node_alipay
node_alipay -->|"payment callback"| node_payment
node_payment -->|"payment/refund result"| node_rocketmq
node_rocketmq -->|"advance order state"| node_order
node_rocketmq -->|"finalize or restore stock"| node_ticket
node_user -->|"owns data"| node_sharded_db
node_ticket -->|"owns inventory data"| node_sharded_db
node_order -->|"owns orders"| node_sharded_db
node_payment -->|"owns payments"| node_sharded_db
node_canal -->|"refreshes ticket state"| node_redis
node_sharded_db -.->|"binlog changes"| node_canal
node_platform_patterns -.->|"shared conventions"| node_user
node_platform_patterns -.->|"shared conventions"| node_ticket

click node_console "https://github.com/nageoffer/12306/blob/main/console-vue/src/main.js"
click node_gateway "https://github.com/nageoffer/12306/blob/main/services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java"
click node_gateway_auth "https://github.com/nageoffer/12306/blob/main/services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/filter/TokenValidateGatewayFilterFactory.java"
click node_aggregation "https://github.com/nageoffer/12306/blob/main/services/aggregation-service/src/main/java/org/opengoofy/index12306/biz/aggregationservice/AggregationServiceApplication.java"
click node_user "https://github.com/nageoffer/12306/blob/main/services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java"
click node_user_registration "https://github.com/nageoffer/12306/blob/main/services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/service/handler/filter/user/UserRegisterCreateChainFilter.java"
click node_ticket "https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java"
click node_purchase "https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/filter/purchase/TrainPurchaseTicketChainFilter.java"
click node_token_bucket "https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/tokenbucket/TicketAvailabilityTokenBucket.java"
click node_order "https://github.com/nageoffer/12306/blob/main/services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/controller/TicketOrderController.java"
click node_payment "https://github.com/nageoffer/12306/blob/main/services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java"
click node_alipay "https://github.com/nageoffer/12306/blob/main/services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/handler/AliPayNativeHandler.java"
click node_user_context "https://github.com/nageoffer/12306/blob/main/frameworks/bizs/user/src/main/java/org/opengoofy/index12306/frameworks/starter/user/core/UserTransmitFilter.java"
click node_platform_patterns "https://github.com/nageoffer/12306/blob/main/frameworks/designpattern/src/main/java/org/opengoofy/index12306/framework/starter/designpattern/chain/AbstractChainContext.java"
click node_sharded_db "https://github.com/nageoffer/12306/blob/main/services/order-service/src/main/resources/shardingsphere-config.yaml"
click node_canal "https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/canal/TicketAvailabilityCacheUpdateHandler.java"

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_console toneBlue
class node_gateway,node_gateway_auth,node_aggregation,node_user,node_user_registration,node_ticket,node_purchase,node_token_bucket,node_order,node_payment,node_alipay toneAmber
class node_user_context,node_platform_patterns toneMint
class node_redis,node_rocketmq,node_sharded_db,node_canal toneRose
```

## Components

### Clients

- [Vue Console](https://github.com/nageoffer/12306/blob/main/console-vue/src/main.js): SPA · `console-vue/src/main.js`

### Business services

- [API Gateway](https://github.com/nageoffer/12306/blob/main/services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java): Spring Cloud gateway · Public routing and JWT validation boundary. · `services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/GatewayServiceApplication.java`
- [JWT filter](https://github.com/nageoffer/12306/blob/main/services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/filter/TokenValidateGatewayFilterFactory.java): gateway filter · `services/gateway-service/src/main/java/org/opengoofy/index12306/biz/gatewayservice/filter/TokenValidateGatewayFilterFactory.java`
- [Aggregation service](https://github.com/nageoffer/12306/blob/main/services/aggregation-service/src/main/java/org/opengoofy/index12306/biz/aggregationservice/AggregationServiceApplication.java): Spring Boot app · Aggregated demo deployment entry point. · `services/aggregation-service/src/main/java/org/opengoofy/index12306/biz/aggregationservice/AggregationServiceApplication.java`
- [User service](https://github.com/nageoffer/12306/blob/main/services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java): identity domain · Owns accounts, profiles, and passengers. · `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/controller/UserLoginController.java`
- [Registration guard](https://github.com/nageoffer/12306/blob/main/services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/service/handler/filter/user/UserRegisterCreateChainFilter.java): chain + Bloom filter · Protects high-volume username checks. · `services/user-service/src/main/java/org/opengoofy/index12306/biz/userservice/service/handler/filter/user/UserRegisterCreateChainFilter.java`
- [Ticket service](https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java): inventory domain · Owns train, fare, seat, and availability APIs. · `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/controller/TicketController.java`
- [Purchase allocator](https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/filter/purchase/TrainPurchaseTicketChainFilter.java): purchase chain · Validates requests and allocates seats. · `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/filter/purchase/TrainPurchaseTicketChainFilter.java`
- [Availability token bucket](https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/tokenbucket/TicketAvailabilityTokenBucket.java): Redis/Lua inventory · Reserves and rolls back ticket availability. · `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/service/handler/ticket/tokenbucket/TicketAvailabilityTokenBucket.java`
- [Order service](https://github.com/nageoffer/12306/blob/main/services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/controller/TicketOrderController.java): order domain · Persists orders, items, and passenger relations. · `services/order-service/src/main/java/org/opengoofy/index12306/biz/orderservice/controller/TicketOrderController.java`
- [Payment service](https://github.com/nageoffer/12306/blob/main/services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java): payment boundary · Creates payments/refunds and receives provider callbacks. · `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/controller/PayCallbackController.java`
- [Alipay](https://github.com/nageoffer/12306/blob/main/services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/handler/AliPayNativeHandler.java): payment provider · `services/pay-service/src/main/java/org/opengoofy/index12306/biz/payservice/handler/AliPayNativeHandler.java`

### Shared platform

Internal Spring Boot starter layer.

- [User context propagation](https://github.com/nageoffer/12306/blob/main/frameworks/bizs/user/src/main/java/org/opengoofy/index12306/frameworks/starter/user/core/UserTransmitFilter.java): shared starter · `frameworks/bizs/user/src/main/java/org/opengoofy/index12306/frameworks/starter/user/core/UserTransmitFilter.java`
- [Platform patterns](https://github.com/nageoffer/12306/blob/main/frameworks/designpattern/src/main/java/org/opengoofy/index12306/framework/starter/designpattern/chain/AbstractChainContext.java): shared starters · Idempotency, cache, IDs, exceptions, and chain/strategy patterns. · `frameworks/designpattern/src/main/java/org/opengoofy/index12306/framework/starter/designpattern/chain/AbstractChainContext.java`

### Data and messaging

- **Redis**: cache and coordination · Supports cache, tokens, Bloom filters, Lua, and worker IDs.
- **RocketMQ**: event bus · Carries delayed close and payment/refund outcomes.
- [Sharded databases](https://github.com/nageoffer/12306/blob/main/services/order-service/src/main/resources/shardingsphere-config.yaml): MyBatis-Plus + ShardingSphere · Service-owned persistence with domain sharding. · `services/order-service/src/main/resources/shardingsphere-config.yaml`
- [Canal cache updater](https://github.com/nageoffer/12306/blob/main/services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/canal/TicketAvailabilityCacheUpdateHandler.java): binlog consumer · Updates ticket cache and tokens after data changes. · `services/ticket-service/src/main/java/org/opengoofy/index12306/biz/ticketservice/canal/TicketAvailabilityCacheUpdateHandler.java`

## Connections

- Vue Console → API Gateway: HTTP API
- API Gateway → JWT filter: validates JWT
- JWT filter → User context propagation: establishes context
- API Gateway → Aggregation service: aggregated mode
- API Gateway → User service: routes identity APIs
- API Gateway → Ticket service: routes ticket APIs
- API Gateway → Order service: routes order APIs
- API Gateway → Payment service: routes payment APIs
- User service → Registration guard: registration flow
- Registration guard → Redis: username Bloom filter
- Ticket service → Purchase allocator: purchase request
- Purchase allocator → Availability token bucket: reserve availability
- Availability token bucket → Redis: atomic Lua tokens
- Ticket service → User service: reads passenger data
- Ticket service → Order service: creates order remotely
- Order service → RocketMQ: delayed close event
- Payment service → Alipay: provider integration
- Alipay → Payment service: payment callback
- Payment service → RocketMQ: payment/refund result
- RocketMQ → Order service: advance order state
- RocketMQ → Ticket service: finalize or restore stock
- User service → Sharded databases: owns data
- Ticket service → Sharded databases: owns inventory data
- Order service → Sharded databases: owns orders
- Payment service → Sharded databases: owns payments
- Canal cache updater → Redis: refreshes ticket state
- Sharded databases → Canal cache updater: binlog changes
- Platform patterns → User service: shared conventions
- Platform patterns → Ticket service: shared conventions
