How sidharthsasikumar/train-ticket-grpc works
This is a single-process Golang gRPC server implementing a train ticketing service. It exposes a gRPC API to:
• purchase tickets
• return receipts
• Users + seat allocations
• remove users (free seats)
• modify seat allocations
• gRPC API surface (service + RPCs)
• core domain/service layer (ticket purchasing, seat allocation, receipts)
• state/storage mechanism (in-memory structures)
• protobuf / codegen boundary
• test harness (server tests)
File tree-driven component mapping (what each folder “means” architecturally)
Top-level files/dirs and the architectural elements they imply:
• main.go
• Composition root / server host
• gRPC server startup, port binding (:50051), handler registration
• Likely implements the gRPC service interface directly or wires it to service
• ticket.proto (README mentions ticketing.proto, but tree shows ticket.proto)
• API contract
• Defines service, RPC methods, request/response messages
• ticket/
• ticket.pb.go, ticket_grpc.pb.go
• Generated code boundary
• Stubs, interfaces, message structs used by server implementation
• service/service.go
• Business logic / domain operations
• Likely owns “seat allocation” logic, user management, receipt creation
• utils/utils.go
• Helper utilities
• Could include validation, formatting, seat computations, etc.
• server_test.go
• System/integration-ish tests of the server behavior (possibly calling RPCs)
• .github/workflows/go.yml
• CI pipeline
• go.mod, go.sum
• Dependencies (grpc, protobuf runtime, etc.)
Entities
• “gRPC Client(s)” (could be CLI, another service, Postman-like gRPC UI)
• “Train Ticketing gRPC Service” (this repo)
• Client → Service: gRPC over HTTP/2
• gRPC Server Runtime
• net listener + grpc.Server
• RPC Handlers / Service Implementation (from main.go and/or wired struct)
• Implements generated interface from ticket/ticket_grpc.pb.go
• Domain/Service Layer (service/service.go)
• Ticket purchase
• Seat allocation
• Receipt generation
• User management
• State Store (In-Memory) (inferred)
• Users map / seat map / receipts collection
• Utilities (utils/utils.go)
• Validation / helpers
Key relationships
• gRPC Server Runtime → RPC Handlers (dispatch)
• RPC Handlers → Domain/Service Layer (calls)
• Domain/Service Layer → In-Memory Store (read/write allocations, receipts)
• Domain/Service Layer → Utilities (helpers)
• RPC Handlers ↔ Protobuf Generated Types (ticket/*.pb.go) (request/response structs)
Handler returns PurchaseResponse/Receipt
Do similarly for:
• GetReceipt: read-only path
• ViewUsers: list allocations
• RemoveUser: delete/free seat
• ModifySeat: reassign seat, handle conflicts
• Client → gRPC Server: “gRPC (HTTP/2)”
• Handler → Service: “method call (Go)”
• Service → Store: “read/write seat allocations, receipts”
• Handler ↔ Protobuf types: “serialize/deserialize protobuf messages”
• PurchaseTicket
• GetReceipt
• ViewUsers
• RemoveUser
• ModifySeat
Architectural patterns present (and what to highlight)
• Contract-first API via protobuf (ticket.proto) + generated stubs
• Layering (Host/Transport → Handler → Business logic → State)
• Single-service, single-process deployment (no evidence of microservices)
• Ephemeral state (if in-memory): highlight limitations (restart loses allocations)
• e.g., “Store guarded by mutex for concurrent RPCs”
Diagramming conventions to use (make it principal-grade)
Clear labels
• Use file-to-component traceability in small text: e.g., “Ticket Service Impl (main.go)” or “Domain Service (service/service.go)”.
• External actors: gray rectangles (Clients)
• Runtime/container: bold boundary (Go process)
• Internal components: blue (handlers), green (business logic), orange (state)
• ticket.proto → ticket/*.pb.go (code generation step)
C4 Level 1 (System Context)
• gRPC Client(s) → Train Ticketing gRPC Service
C4 Level 2 (Container)
• One container: “train-ticket-grpc (Go gRPC server)”
• expose port 50051
C4 Level 3 (Components inside container)
• gRPC Server
• TicketService RPC Implementation (implements generated interface)
• Ticketing Domain Service
• Purchase
• Receipt
• Seat Allocation
• User Admin
• In-memory Store
• Utils
• Protobuf Generated Types
A codegen side note:
• ticket.proto (source) -> protoc -> generated stubs
That’s the most accurate representation given the repository: one deployable server, clear RPC contract, internal service logic, and in-memory state.