# amar-preet/go-crud-twirp architecture

> Architecture diagram of the GitHub repository amar-preet/go-crud-twirp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amar-preet/go-crud-twirp
- Repository: https://github.com/amar-preet/go-crud-twirp

## Overview

##### Project type and purpose
- This is a backend Go service that implements a simple CRUD API (“Albums”) over HTTP using Twitch’s Twirp RPC framework, backed by a PostgreSQL database.
- It also provides a command-line client (in cmd/client) that uses the generated Twirp client to invoke the server.

##### File structure
- Top-level:
- cmd/server: entry point for the HTTP/Twirp server
- cmd/client: entry point for a CLI client
- rpc/twirpAPI: the .proto definition, and generated Twirp server/client stubs
- internal/twirpAPI: hand-written server implementation behind the Twirp interface
- db: schema, SQLC configuration, generated query code, and connection setup (pg.go)
- Makefile: build commands for generating code (proto, SQLC) and running server/client
- Patterns:
- RPC layer (Twirp)
- Clean separation: transport (cmd/server) → RPC interface → business logic in internal → data layer in db
- Code generation stages: protobuf → Twirp stubs; SQL files → SQLC-generated Go code

##### README for additional insights
- The README documents how to generate code (`make proto`, SQLC runs via sqlc.yaml), start the server, start the client, and how to hit each endpoint in both Protobuf and JSON.

##### Elements
- Another for handwritten code (internal/twirpAPI, cmd, db/pg.go)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Codegen
    subgraph "Build & Codegen"
        direction TB
        Makefile["Makefile"]:::handwritten
        Makefile -->|"runs protoc"| Protoc["protoc"]:::external
        Makefile -->|"runs SQLC"| SQLC["sqlc"]:::external

        subgraph "Generated Twirp Code"
            direction TB
            ProtoDef["twirp.proto"]:::generated
            PBGen["twirp.pb.go"]:::generated
            TwirpStub["twirp.twirp.go"]:::generated
            Protoc --> ProtoDef
            Protoc --> PBGen
            Protoc --> TwirpStub
        end

        subgraph "Generated SQLC Code"
            direction TB
            Schema["schema.sql"]:::external
            QuerySQL["query.sql"]:::external
            SQLCGenDB["db.go"]:::generated
            SQLCModels["models.go"]:::generated
            SQLCQueries["query.sql.go"]:::generated
            Schema --> SQLCGenDB
            QuerySQL --> SQLCQueries
            SQLC --> SQLCGenDB
            SQLC --> SQLCModels
            SQLC --> SQLCQueries
        end
    end

    %% Runtime
    subgraph "Runtime"
        direction TB
        subgraph "Client Side"
            direction TB
            CLI["Client CLI"]:::handwritten
        end

        subgraph "Server Side"
            direction TB
            HTTPServer["Twirp HTTP Server"]:::handwritten
            subgraph "Twirp API Layer"
                direction TB
                ProtoDef
                PBGen
                TwirpStub
            end
            subgraph "Business Logic Handlers"
                direction TB
                Handlers["server.go / server_test.go"]:::handwritten
            end
            subgraph "Data Access Layer"
                direction TB
                DBConn["pg.go"]:::handwritten
                SQLCGenDB
                SQLCModels
                SQLCQueries
            end
            Postgres["PostgreSQL"]:::external
        end
    end

    %% Data Flow
    CLI -->|"HTTP/JSON or HTTP/Protobuf"| HTTPServer
    HTTPServer -->|"invokes"| TwirpStub
    TwirpStub -->|"calls"| Handlers
    Handlers -->|"uses"| DBConn
    DBConn -->|"executes via SQLC"| SQLCQueries
    SQLCQueries -->|"SQL"| Postgres

    %% Click Events
    click CLI "https://github.com/amar-preet/go-crud-twirp/blob/master/cmd/client/main.go"
    click HTTPServer "https://github.com/amar-preet/go-crud-twirp/blob/master/cmd/server/main.go"
    click ProtoDef "https://github.com/amar-preet/go-crud-twirp/blob/master/rpc/twirpAPI/twirp.proto"
    click PBGen "https://github.com/amar-preet/go-crud-twirp/blob/master/rpc/twirpAPI/twirp.pb.go"
    click TwirpStub "https://github.com/amar-preet/go-crud-twirp/blob/master/rpc/twirpAPI/twirp.twirp.go"
    click Handlers "https://github.com/amar-preet/go-crud-twirp/blob/master/internal/twirpAPI/server.go"
    click DBConn "https://github.com/amar-preet/go-crud-twirp/blob/master/db/pg.go"
    click SQLCGenDB "https://github.com/amar-preet/go-crud-twirp/blob/master/db/db/db.go"
    click SQLCModels "https://github.com/amar-preet/go-crud-twirp/blob/master/db/db/models.go"
    click SQLCQueries "https://github.com/amar-preet/go-crud-twirp/blob/master/db/db/query.sql.go"
    click Schema "https://github.com/amar-preet/go-crud-twirp/blob/master/db/schema.sql"
    click QuerySQL "https://github.com/amar-preet/go-crud-twirp/blob/master/db/query.sql"
    click Makefile "https://github.com/amar-preet/go-crud-twirp/tree/master/Makefile"

    %% Styles
    classDef generated fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef handwritten fill:#E5F8E0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE4B5,stroke:#333,stroke-width:1px
```
