# ashiqyousuf/sbank architecture

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

- Interactive diagram: https://gitdiagram.com/ashiqyousuf/sbank
- Repository: https://github.com/ashiqyousuf/sbank

## Overview

#### Purpose and process entry point
`sbank` is a Go banking-service backend: accounts, transfers, users, authentication sessions/tokens, and user lifecycle RPCs. `main.go` is the composition root, loading configuration and starting the service stack. The repository exposes both native gRPC and HTTP/JSON through a gRPC-Gateway-generated bridge; legacy/direct HTTP handlers also exist under `api/`.

#### API delivery surfaces
The primary contract is protobuf-defined user RPCs in `proto/service_simple_bank.proto`, with request/message definitions in `proto/rpc_create_user.proto`, `proto/rpc_login_user.proto`, and `proto/rpc_update_user.proto`. Generated server, gRPC, and gateway bindings reside in `pb/service_simple_bank_grpc.pb.go` and `pb/service_simple_bank.pb.gw.go`. OpenAPI/Swagger static assets are shipped in `doc/swagger/`, embedded through `doc/statik/statik.go`.

#### gRPC application layer
`gapi/server.go` implements the protobuf service and owns request handling. RPC implementations in `gapi/rpc_create_user.go`, `gapi/rpc_login_user.go`, and `gapi/rpc_update_user.go` convert protobuf inputs to persistence/auth operations and return API messages. `gapi/authorization.go` provides gRPC authorization interception, while `gapi/error.go` maps domain/storage failures to transport-level gRPC errors. This interceptor boundary does not automatically apply to gateway HTTP requests.

#### HTTP API layer
`api/server.go` provides an HTTP server/route layer alongside the gRPC-first API. Resource handlers are separated by banking concern: `api/account.go`, `api/transfer.go`, and `api/user.go`. `api/middleware.go` is the HTTP cross-cutting boundary for concerns such as authentication, distinct from gRPC interception. `api/validator.go` validates inbound HTTP payloads.

#### Persistence and transactional banking core
PostgreSQL schema evolution is defined in `db/migration/000001_init_schema.up.sql`, `db/migration/000002_add_users.up.sql`, and `db/migration/000003_add_sessions.up.sql`. SQL query specifications live in `db/query/account.sql`, `db/query/transfer.sql`, and `db/query/session.sql`; sqlc-generated typed access code is under `db/sqlc/`. `db/sqlc/store.go` is the principal persistence boundary, coordinating queries and likely transaction-scoped account/transfer/entry changes, preventing handlers from directly assembling banking transactions.

#### Identity, sessions, and credentials
User records and durable sessions are modeled via `db/query/user.sql`, `db/query/session.sql`, and generated types in `db/sqlc/models.go`. The token abstraction in `token/maker.go` allows authentication implementation substitution; `token/jwt_maker.go` and `token/paseto_maker.go` implement JWT and PASETO issuance/verification. Password hashing/verification belongs to `util/password.go`, keeping raw credentials out of transport and store layers.

#### Asynchronous verification capability
`worker/distributor.go` abstracts task publication, while `worker/task_send_verify_email.go` defines the email-verification task payload/work unit. This establishes an async boundary for external email delivery, although no concrete queue or mail-provider implementation appears in the tree.

#### Runtime and infrastructure
The runtime is Go (module metadata: `go.mod`) with PostgreSQL implied by SQL migrations and sqlc usage. Configuration is loaded through `util/config.go` with environment values represented by `app.env`. Protocol infrastructure includes gRPC, protobuf, gRPC-Gateway HTTP translation, and embedded Swagger UI/OpenAPI documentation.

Main entry points: [`gapi/rpc_create_user.go`](https://github.com/ashiqyousuf/sbank/blob/main/gapi/rpc_create_user.go) (User RPC handlers), [`gapi/server.go`](https://github.com/ashiqyousuf/sbank/blob/main/gapi/server.go) (gRPC application server), [`main.go`](https://github.com/ashiqyousuf/sbank/blob/main/main.go) (Service composition), [`pb/service_simple_bank.pb.gw.go`](https://github.com/ashiqyousuf/sbank/blob/main/pb/service_simple_bank.pb.gw.go) (gRPC-Gateway HTTP bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["API Contracts"]
  node_proto["User RPC contract<br/>protobuf definitions"]
  node_generated["gRPC &amp; gateway bindings<br/>generated protobuf code"]
  node_swagger["Embedded API documentation<br/>Swagger/OpenAPI assets<br/>[statik.go]"]
end

subgraph group_transport["Transport Layers"]
  node_gateway["gRPC-Gateway HTTP bridge<br/>HTTP/JSON translator"]
  node_grpc_server["gRPC application server<br/>protobuf service implementation<br/>[server.go]"]
  node_grpc_rpcs["User RPC handlers<br/>gRPC request handlers<br/>[rpc_create_user.go]"]
  node_grpc_auth["gRPC authorization<br/>interceptor<br/>[authorization.go]"]
  node_http_server["Direct HTTP API<br/>HTTP route layer<br/>[server.go]"]
  node_http_handlers["Banking HTTP handlers<br/>account, transfer, user handlers<br/>[account.go]"]
  node_http_middleware["HTTP auth &amp; validation<br/>HTTP cross-cutting layer<br/>[middleware.go]"]
end

subgraph group_core["Banking Core"]
  node_store["Transactional store<br/>sqlc persistence boundary<br/>[store.go]"]
end

subgraph group_identity["Identity &amp; Async"]
  node_passwords["Password credentials<br/>password hashing<br/>[password.go]"]
  node_tokens["Token abstraction<br/>authentication tokens<br/>[maker.go]"]
  node_verification_tasks["Verification task publisher<br/>async task boundary<br/>[distributor.go]"]
end

subgraph group_data["Data Layer"]
  node_sql_queries["SQL query specifications<br/>sqlc inputs<br/>[account.sql]"]
  node_database[("PostgreSQL<br/>relational database")]
end

node_main{{"Service composition<br/>Go entry point<br/>[main.go]"}}
node_config["Runtime configuration<br/>configuration loader<br/>[config.go]"]

node_main -->|"loads"| node_config
node_main -->|"starts"| node_grpc_server
node_main -->|"starts"| node_http_server
node_main -->|"starts"| node_gateway
node_proto -->|"generates"| node_generated
node_generated -->|"service interface"| node_grpc_server
node_generated -->|"route bindings"| node_gateway
node_gateway -->|"translates HTTP/JSON to RPC"| node_grpc_server
node_grpc_auth -->|"intercepts RPCs"| node_grpc_server
node_grpc_server -->|"dispatches"| node_grpc_rpcs
node_grpc_rpcs -->|"persists users and sessions"| node_store
node_grpc_rpcs -->|"hashes credentials"| node_passwords
node_grpc_rpcs -->|"issues and verifies"| node_tokens
node_grpc_rpcs -.->|"publishes verification"| node_verification_tasks
node_http_server -->|"applies"| node_http_middleware
node_http_middleware -->|"guards requests"| node_http_handlers
node_http_handlers -->|"executes banking operations"| node_store
node_http_middleware -->|"authenticates"| node_tokens
node_store -->|"uses generated access from"| node_sql_queries
node_sql_queries -->|"reads and writes"| node_database
node_swagger -.->|"documents HTTP API"| node_gateway

click node_main "https://github.com/ashiqyousuf/sbank/blob/main/main.go"
click node_config "https://github.com/ashiqyousuf/sbank/blob/main/util/config.go"
click node_proto "https://github.com/ashiqyousuf/sbank/blob/main/proto/service_simple_bank.proto"
click node_generated "https://github.com/ashiqyousuf/sbank/blob/main/pb/service_simple_bank_grpc.pb.go"
click node_gateway "https://github.com/ashiqyousuf/sbank/blob/main/pb/service_simple_bank.pb.gw.go"
click node_grpc_server "https://github.com/ashiqyousuf/sbank/blob/main/gapi/server.go"
click node_grpc_rpcs "https://github.com/ashiqyousuf/sbank/blob/main/gapi/rpc_create_user.go"
click node_grpc_auth "https://github.com/ashiqyousuf/sbank/blob/main/gapi/authorization.go"
click node_http_server "https://github.com/ashiqyousuf/sbank/blob/main/api/server.go"
click node_http_handlers "https://github.com/ashiqyousuf/sbank/blob/main/api/account.go"
click node_http_middleware "https://github.com/ashiqyousuf/sbank/blob/main/api/middleware.go"
click node_store "https://github.com/ashiqyousuf/sbank/blob/main/db/sqlc/store.go"
click node_passwords "https://github.com/ashiqyousuf/sbank/blob/main/util/password.go"
click node_tokens "https://github.com/ashiqyousuf/sbank/blob/main/token/maker.go"
click node_verification_tasks "https://github.com/ashiqyousuf/sbank/blob/main/worker/distributor.go"
click node_sql_queries "https://github.com/ashiqyousuf/sbank/blob/main/db/query/account.sql"
click node_database "https://github.com/ashiqyousuf/sbank/blob/main/db/migration/000001_init_schema.up.sql"
click node_swagger "https://github.com/ashiqyousuf/sbank/blob/main/doc/statik/statik.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_proto,node_generated,node_swagger toneBlue
class node_gateway,node_grpc_server,node_grpc_rpcs,node_grpc_auth,node_http_server,node_http_handlers,node_http_middleware toneAmber
class node_store toneMint
class node_passwords,node_tokens,node_verification_tasks toneRose
class node_sql_queries,node_database toneIndigo
class node_main,node_config toneNeutral
```

## Components

### API Contracts

- [User RPC contract](https://github.com/ashiqyousuf/sbank/blob/main/proto/service_simple_bank.proto): protobuf definitions · `proto/service_simple_bank.proto`
- [gRPC & gateway bindings](https://github.com/ashiqyousuf/sbank/blob/main/pb/service_simple_bank_grpc.pb.go): generated protobuf code · `pb/service_simple_bank_grpc.pb.go`
- [Embedded API documentation](https://github.com/ashiqyousuf/sbank/blob/main/doc/statik/statik.go): Swagger/OpenAPI assets · `doc/statik/statik.go`

### Transport Layers

- [gRPC-Gateway HTTP bridge](https://github.com/ashiqyousuf/sbank/blob/main/pb/service_simple_bank.pb.gw.go): HTTP/JSON translator · Gateway requests bypass gRPC authorization interception. · `pb/service_simple_bank.pb.gw.go`
- [gRPC application server](https://github.com/ashiqyousuf/sbank/blob/main/gapi/server.go): protobuf service implementation · `gapi/server.go`
- [User RPC handlers](https://github.com/ashiqyousuf/sbank/blob/main/gapi/rpc_create_user.go): gRPC request handlers · `gapi/rpc_create_user.go`
- [gRPC authorization](https://github.com/ashiqyousuf/sbank/blob/main/gapi/authorization.go): interceptor · `gapi/authorization.go`
- [Direct HTTP API](https://github.com/ashiqyousuf/sbank/blob/main/api/server.go): HTTP route layer · `api/server.go`
- [Banking HTTP handlers](https://github.com/ashiqyousuf/sbank/blob/main/api/account.go): account, transfer, user handlers · `api/account.go`
- [HTTP auth & validation](https://github.com/ashiqyousuf/sbank/blob/main/api/middleware.go): HTTP cross-cutting layer · `api/middleware.go`

### Banking Core

- [Transactional store](https://github.com/ashiqyousuf/sbank/blob/main/db/sqlc/store.go): sqlc persistence boundary · Coordinates typed queries and banking transactions. · `db/sqlc/store.go`

### Identity & Async

- [Password credentials](https://github.com/ashiqyousuf/sbank/blob/main/util/password.go): password hashing · `util/password.go`
- [Token abstraction](https://github.com/ashiqyousuf/sbank/blob/main/token/maker.go): authentication tokens · Supports JWT and PASETO issuance and verification. · `token/maker.go`
- [Verification task publisher](https://github.com/ashiqyousuf/sbank/blob/main/worker/distributor.go): async task boundary · Publishes email-verification work without a concrete queue implementation. · `worker/distributor.go`

### Data Layer

- [SQL query specifications](https://github.com/ashiqyousuf/sbank/blob/main/db/query/account.sql): sqlc inputs · `db/query/account.sql`
- [PostgreSQL](https://github.com/ashiqyousuf/sbank/blob/main/db/migration/000001_init_schema.up.sql): relational database · `db/migration/000001_init_schema.up.sql`

### Other components

- [Service composition](https://github.com/ashiqyousuf/sbank/blob/main/main.go): Go entry point · Loads configuration and starts the service stack. · `main.go`
- [Runtime configuration](https://github.com/ashiqyousuf/sbank/blob/main/util/config.go): configuration loader · `util/config.go`

## Connections

- Service composition → Runtime configuration: loads
- Service composition → gRPC application server: starts
- Service composition → Direct HTTP API: starts
- Service composition → gRPC-Gateway HTTP bridge: starts
- User RPC contract → gRPC & gateway bindings: generates
- gRPC & gateway bindings → gRPC application server: service interface
- gRPC & gateway bindings → gRPC-Gateway HTTP bridge: route bindings
- gRPC-Gateway HTTP bridge → gRPC application server: translates HTTP/JSON to RPC
- gRPC authorization → gRPC application server: intercepts RPCs
- gRPC application server → User RPC handlers: dispatches
- User RPC handlers → Transactional store: persists users and sessions
- User RPC handlers → Password credentials: hashes credentials
- User RPC handlers → Token abstraction: issues and verifies
- User RPC handlers → Verification task publisher: publishes verification
- Direct HTTP API → HTTP auth & validation: applies
- HTTP auth & validation → Banking HTTP handlers: guards requests
- Banking HTTP handlers → Transactional store: executes banking operations
- HTTP auth & validation → Token abstraction: authenticates
- Transactional store → SQL query specifications: uses generated access from
- SQL query specifications → PostgreSQL: reads and writes
- Embedded API documentation → gRPC-Gateway HTTP bridge: documents HTTP API