# sidharthsasikumar/train-ticket-grpc architecture

> Architecture diagram of the GitHub repository sidharthsasikumar/train-ticket-grpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sidharthsasikumar/train-ticket-grpc
- Repository: https://github.com/sidharthsasikumar/train-ticket-grpc

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% View A: System Context
    %% =======================
    subgraph "View A — System Context"
        direction TB
        Client["gRPC Client(s)\n(CLI / other service / gRPC UI)"]:::external

        subgraph "Train Ticketing gRPC Service (single Go process)"
            direction TB
            SvcEntry["Public gRPC Endpoint\n:50051 (HTTP/2)"]:::runtime
        end

        Client -->|"gRPC(HTTP/2)+protobuf"| SvcEntry
    end

    %% =======================
    %% View B: Container + Components
    %% =======================
    subgraph "View B — Container / Component Architecture (inside the process)"
        direction TB

        subgraph "Go gRPC Server Process"
            direction TB

            Main["Composition Root / Server Host\n(main.go)"]:::runtime
            GRPC["gRPC Server Runtime\n(net.Listener + grpc.Server)"]:::runtime

            subgraph "Transport Layer (RPC Surface)"
                direction TB
                RPCImpl["TicketService RPC Implementation\n(implements generated interface)"]:::handler

                RPCs["RPC Methods\n- PurchaseTicket\n- GetReceipt\n- ViewUsers\n- RemoveUser\n- ModifySeat"]:::handler
            end

            subgraph "Business / Domain Layer (service/service.go)"
                direction TB
                Domain["Ticketing Domain Service"]:::domain
                Purchase["Ticket Purchase"]:::domain
                Receipt["Receipt Retrieval"]:::domain
                Seat["Seat Allocation"]:::domain
                Users["User Management"]:::domain
            end

            Store[("In-memory State Store\n(users/seats/receipts)\nNo persistence")]:::store

            Utils["Utilities / Helpers\n(utils/utils.go)"]:::util

            subgraph "API Contract & Codegen Boundary"
                direction TB
                Proto["Protobuf API Contract\n(ticket.proto)"]:::contract
                GenMsg["Generated Types\n(ticket.pb.go)"]:::generated
                GenGrpc["Generated gRPC Stubs/Interfaces\n(ticket_grpc.pb.go)"]:::generated
            end
        end

        %% Wiring / calls
        Main -->|"starts+registers"| GRPC
        GRPC -->|"dispatches RPC"| RPCImpl
        RPCImpl -->|"exposes"| RPCs

        RPCImpl -->|"method-call(Go)"| Domain
        Domain -->|"delegates"| Purchase
        Domain -->|"delegates"| Receipt
        Domain -->|"delegates"| Seat
        Domain -->|"delegates"| Users

        Purchase -->|"read/write allocations+receipt"| Store
        Receipt -->|"read receipt"| Store
        Seat -->|"read/write seats"| Store
        Users -->|"list/remove user data"| Store

        Domain -->|"uses"| Utils
        RPCImpl <-->|"serialize/deserialize"| GenMsg
        RPCImpl -->|"implements"| GenGrpc

        %% Codegen relationship (build-time)
        Proto -.->|"protoc codegen"| GenMsg
        Proto -.->|"protoc codegen"| GenGrpc

        %% Note on behavior
        NoteState["Note: Ephemeral state\nRestart loses allocations/receipts"]:::note
        Store --- NoteState
    end

    %% =======================
    %% View C: Key Sequences (2)
    %% =======================
    subgraph "View C — Sequence / Data Flow (selected RPCs)"
        direction TB

        subgraph "C1: PurchaseTicket"
            direction TB
            C1Client["Client"]:::external
            C1Handler["PurchaseTicket Handler\n(RPCImpl)"]:::handler
            C1Svc["Service: Purchase + Seat Allocation\n(service/service.go)"]:::domain
            C1Store[("In-memory Store")]:::store
            C1Utils["Utils"]:::util

            C1Client -->|"PurchaseTicket(PurchaseRequest)"| C1Handler
            C1Handler -->|"validate(input)"| C1Utils
            C1Handler -->|"call purchase() / allocateSeat()"| C1Svc
            C1Svc -->|"check availability\nassign seat"| C1Store
            C1Svc -->|"persist allocation+receipt"| C1Store
            C1Handler -->|"PurchaseResponse/Receipt"| C1Client
        end

        subgraph "C2: ModifySeat"
            direction TB
            C2Client["Client"]:::external
            C2Handler["ModifySeat Handler\n(RPCImpl)"]:::handler
            C2Svc["Service: Seat Reassignment\n(service/service.go)"]:::domain
            C2Store[("In-memory Store")]:::store
            C2Utils["Utils"]:::util

            C2Client -->|"ModifySeat(ModifySeatRequest)"| C2Handler
            C2Handler -->|"validate(input)"| C2Utils
            C2Handler -->|"call modifySeat()"| C2Svc
            C2Svc -->|"read current allocation"| C2Store
            C2Svc -->|"check conflicts\nupdate seat mapping"| C2Store
            C2Handler -->|"ModifySeatResponse"| C2Client
        end
    end

    %% =======================
    %% Quality / Delivery
    %% =======================
    subgraph "Quality & Delivery"
        direction TB
        Tests["Server Test Harness\n(server_test.go)"]:::test
        CI["GitHub Actions CI\n(.github/workflows/go.yml)"]:::ci
        Mod["Go Module\n(go.mod)"]:::deps
        Sum["Dependency Checksums\n(go.sum)"]:::deps

        CI -->|"go test"| Tests
        Tests -->|"starts server / calls RPCs"| GRPC
        CI -->|"uses"| Mod
        CI -->|"uses"| Sum
    end

    %% =======================
    %% Click Events (component_mapping)
    %% =======================
    click Main "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/main.go"
    click Proto "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/ticket.proto"
    click GenMsg "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/ticket/ticket.pb.go"
    click GenGrpc "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/ticket/ticket_grpc.pb.go"
    click Domain "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/service/service.go"
    click Utils "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/utils/utils.go"
    click Tests "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/server_test.go"
    click CI "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/.github/workflows/go.yml"
    click Mod "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/go.mod"
    click Sum "https://github.com/sidharthsasikumar/train-ticket-grpc/blob/main/go.sum"

    %% =======================
    %% Styles
    %% =======================
    classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
    classDef runtime fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:1px
    classDef handler fill:#bfdbfe,stroke:#2563eb,color:#0f172a,stroke-width:1px
    classDef domain fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:1px
    classDef store fill:#ffedd5,stroke:#ea580c,color:#7c2d12,stroke-width:1px
    classDef util fill:#fef9c3,stroke:#ca8a04,color:#422006,stroke-width:1px
    classDef contract fill:#ede9fe,stroke:#7c3aed,color:#2e1065,stroke-width:1px
    classDef generated fill:#f3e8ff,stroke:#9333ea,color:#2e1065,stroke-dasharray: 5 3,stroke-width:1px
    classDef test fill:#ffe4e6,stroke:#e11d48,color:#4c0519,stroke-width:1px
    classDef ci fill:#ccfbf1,stroke:#0f766e,color:#042f2e,stroke-width:1px
    classDef deps fill:#f1f5f9,stroke:#475569,color:#0f172a,stroke-width:1px
    classDef note fill:#fff7ed,stroke:#9a3412,color:#7c2d12,stroke-dasharray: 3 3,stroke-width:1px
```
