# starptech/go-web architecture

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

- Interactive diagram: https://gitdiagram.com/starptech/go-web
- Repository: https://github.com/starptech/go-web

## Overview

##### Project type and purpose
- This is a monolithic, full-stack web application written in Go, following the “project-layout” conventions.
- The backend is an HTTP server (Echo) exposing REST and server-side rendered pages; the frontend is a React UI bundled by Parcel and injected into Go templates.
- It uses CockroachDB for persistent storage, Redis for caching, and supports i18n.

##### File structure
- Top-level:
- main.go – entry point
- internal/ – all Go code, further split into controllers, core (middleware, router, server, error handling, templating), models, store, cache, context, i18n
- config/ – configuration loader
- scripts/ – DB bootstrap SQL
- docker-compose.yml – orchestrates CockroachDB & Redis
- web/ – frontend assets, React components, styles, Go templates
- Tests live alongside their controllers in internal/controller.
- CI/CD: .github/workflows (go.yml, goreleaser.yml), Makefile, goreleaser config.

##### Key insights from README
- Stack calls out Echo, GORM, validator, godotenv, gotext, Redis, CockroachDB, Parcel, React.
- Developer workflow: docker-compose to spin up infra, build web with Parcel, then run main.go.
- CI is GitHub Actions; releases via goreleaser.

a. Main components
- Client (Browser with React UI)
- HTTP Layer (Echo server + middleware)
- Controller Layer (healthcheck, user, user-list controllers)
- Business Layer / Core (error handler, validator, template engine, router, context injection)
- Data Layer (UserStore via GORM on CockroachDB, CacheStore on Redis)
- i18n subsystem (gotext, .po files under locales/)
- Build & Infra (Parcel bundler, Docker Compose for DB & Redis, CI/CD pipelines)
b. Relationships & interactions
– Client → HTTP Layer via REST or SSR endpoints
– HTTP Layer invokes Controller → Core services → Store layers → External data stores
– Stores talk to CockroachDB (SQL) or Redis (cache) over TCP
– Templating engine merges data + React bundles into HTML delivered to Client
– Docker Compose isolates DB and Redis; .env/config inject into server at startup
– CI/CD pipelines pull from GitHub, run tests/lints, build Go binaries (goreleaser), and can deploy to Heroku
c. Architectural patterns
– Layered (Transport → Controller → Service/Core → Repository)
– Dependency Injection via app_context
– Middleware chain for cross-cutting concerns (logging, error handling, request context)
– Monolith with clear separation of concerns, not microservices
d. Key technologies to annotate
– Echo (HTTP + middleware)
– validator, godotenv, env loader
– GORM for ORM
– Redis client
– Go templates + Parcel + React for frontend
– CockroachDB
– gotext for localization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Browser" 
        style ClientUI fill:#bbdefb,stroke:#333,stroke-width:1px
        ClientUI["React UI\n(web/src/app)"] 
    end

    %% Server Monolith
    subgraph "Server Monolith"
        style ServerMono fill:#c8e6c9,stroke:#333,stroke-width:1px

        Entry["main.go"] 
        click Entry "https://github.com/starptech/go-web/blob/master/main.go"

        subgraph "Configuration"
            Config["config/config.go"] 
            click Config "https://github.com/starptech/go-web/blob/master/config/config.go"
        end

        subgraph "HTTP Layer"
            Server["Echo Server\n(internal/core/server.go)"] 
            click Server "https://github.com/starptech/go-web/blob/master/internal/core/server.go"
            Router["Router\n(internal/core/router.go)"] 
            click Router "https://github.com/starptech/go-web/blob/master/internal/core/router.go"
            Server --> Router
        end

        subgraph "Middleware & Context"
            Middleware["App Context Middleware\n(internal/core/middleware/app_context.go)"]
            click Middleware "https://github.com/starptech/go-web/blob/master/internal/core/middleware/app_context.go"
            AppContext["App Context\n(internal/context/app_context.go)"]
            click AppContext "https://github.com/starptech/go-web/blob/master/internal/context/app_context.go"
        end

        subgraph "Controllers"
            Health["HealthCheck Controller\n(internal/controller/healthcheck.go)"]
            click Health "https://github.com/starptech/go-web/blob/master/internal/controller/healthcheck.go"
            UserList["UserList Controller\n(internal/controller/user-list.go)"]
            click UserList "https://github.com/starptech/go-web/blob/master/internal/controller/user-list.go"
            User["User Controller\n(internal/controller/user.go)"]
            click User "https://github.com/starptech/go-web/blob/master/internal/controller/user.go"
        end

        subgraph "Core Services"
            ErrorHandler["Error Handler\n(internal/core/error_handler.go)"]
            click ErrorHandler "https://github.com/starptech/go-web/blob/master/internal/core/error_handler.go"
            Validator["Validator\n(internal/core/validator.go)"]
            click Validator "https://github.com/starptech/go-web/blob/master/internal/core/validator.go"
            Template["Template Engine\n(internal/core/template.go)"]
            click Template "https://github.com/starptech/go-web/blob/master/internal/core/template.go"
            CacheStoreCore["Cache Store\n(internal/core/cache_store.go)"]
            click CacheStoreCore "https://github.com/starptech/go-web/blob/master/internal/core/cache_store.go"
            UserStoreCore["User Store\n(internal/core/user_store.go)"]
            click UserStoreCore "https://github.com/starptech/go-web/blob/master/internal/core/user_store.go"
        end

        subgraph "Data Models"
            Models["Models\n(internal/models/models.go)"]
            click Models "https://github.com/starptech/go-web/blob/master/internal/models/models.go"
            UserModel["User Model\n(internal/models/user.go)"]
            click UserModel "https://github.com/starptech/go-web/blob/master/internal/models/user.go"
        end

        subgraph "Repositories"
            GORMStore["User GORM Store\n(internal/store/user.go)"]
            click GORMStore "https://github.com/starptech/go-web/blob/master/internal/store/user.go"
            CacheClientInit["Cache Client Init\n(internal/cache/cache.go)"]
            click CacheClientInit "https://github.com/starptech/go-web/blob/master/internal/cache/cache.go"
            CacheStore["Redis Cache Store\n(internal/store/cache.go)"]
            click CacheStore "https://github.com/starptech/go-web/blob/master/internal/store/cache.go"
        end

        subgraph "i18n"
            I18n["i18n Subsystem\n(internal/i18n/i18n.go)"]
            click I18n "https://github.com/starptech/go-web/blob/master/internal/i18n/i18n.go"
            POFile["Default Locale\n(locales/en/default.po)"]
            click POFile "https://github.com/starptech/go-web/blob/master/locales/en/default.po"
        end

        %% Internal connections
        Entry --> Config
        Entry --> Server
        Server --> Middleware
        Middleware --> Router
        Router --> Health
        Router --> UserList
        Router --> User
        Health --> ErrorHandler
        UserList --> Validator
        UserList --> UserStoreCore
        User --> Validator
        User --> UserStoreCore
        UserStoreCore --> GORMStore
        UserStoreCore --> CacheStoreCore
        CacheStoreCore --> CacheStore
        CacheStore --> CacheClientInit
        GORMStore --> Models
        Models --> UserModel
        Template --> UserList
        Template --> User
        Entry --> I18n

    end

    %% Data Stores
    subgraph "Data Stores"
        style DataStores fill:#ffe0b2,stroke:#333,stroke-width:1px
        Cockroach["CockroachDB\n(docker-compose.yml)"]
        Redis["Redis\n(docker-compose.yml)"]
        click Cockroach "https://github.com/starptech/go-web/blob/master/docker-compose.yml"
        click Redis "https://github.com/starptech/go-web/blob/master/docker-compose.yml"
    end

    %% Frontend Build
    subgraph "Frontend Build"
        style FrontendBuild fill:#e0e0e0,stroke:#333,stroke-width:1px
        Parcel["Parcel Bundler\n(web/package.json)"]
        click Parcel "https://github.com/starptech/go-web/blob/master/web/package.json"
        Babel[".babelrc\n(web/.babelrc)"]
        click Babel "https://github.com/starptech/go-web/blob/master/web/.babelrc"
        ESLint["ESLint Config\n(web/.eslintrc.json)"]
        click ESLint "https://github.com/starptech/go-web/blob/master/web/.eslintrc.json"
    end

    %% Frontend Assets
    subgraph "Web Assets"
        style WebAssets fill:#bbdefb,stroke:#333,stroke-width:1px
        AppJS["App Main\n(web/src/app/app.js)"]
        click AppJS "https://github.com/starptech/go-web/blob/master/web/src/app/app.js"
        IndexJS["App Entry\n(web/src/app/index.js)"]
        click IndexJS "https://github.com/starptech/go-web/blob/master/web/src/app/index.js"
        Header["Header Component\n(web/src/app/components/header.js)"]
        click Header "https://github.com/starptech/go-web/blob/master/web/src/app/components/header.js"
        LikeBtn["Like Button\n(web/src/app/components/like-button.js)"]
        click LikeBtn "https://github.com/starptech/go-web/blob/master/web/src/app/components/like-button.js"
        StylesApp["App Styles\n(web/src/app/styles.scss)"]
        click StylesApp "https://github.com/starptech/go-web/blob/master/web/src/app/styles.scss"
        GlobalHTML["Global Template\n(web/src/global/global.html)"]
        click GlobalHTML "https://github.com/starptech/go-web/blob/master/web/src/global/global.html"
        GlobalIndex["Global Entry\n(web/src/global/index.js)"]
        click GlobalIndex "https://github.com/starptech/go-web/blob/master/web/src/global/index.js"
        GlobalStyles["Global Styles\n(web/src/global/styles.scss)"]
        click GlobalStyles "https://github.com/starptech/go-web/blob/master/web/src/global/styles.scss"
    end

    subgraph "Server Templates"
        style Templates fill:#ffe0b2,stroke:#333,stroke-width:1px
        BaseLayout["Base Layout\n(web/templates/layouts/base.html)"]
        click BaseLayout "https://github.com/starptech/go-web/blob/master/web/templates/layouts/base.html"
        UserListPage["User List Page\n(web/templates/pages/user-list.html)"]
        click UserListPage "https://github.com/starptech/go-web/blob/master/web/templates/pages/user-list.html"
        UserPage["User Page\n(web/templates/pages/user.html)"]
        click UserPage "https://github.com/starptech/go-web/blob/master/web/templates/pages/user.html"
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        style CICD fill:#e0e0e0,stroke:#333,stroke-width:1px
        GoWorkflow["Go CI\n(.github/workflows/go.yml)"]
        click GoWorkflow "https://github.com/starptech/go-web/blob/master/.github/workflows/go.yml"
        ReleaseWorkflow["Goreleaser\n(.github/workflows/goreleaser.yml)"]
        click ReleaseWorkflow "https://github.com/starptech/go-web/blob/master/.github/workflows/goreleaser.yml"
        Makefile["Makefile"]
        click Makefile "https://github.com/starptech/go-web/tree/master/Makefile"
    end

    %% Compose connections
    DockerCompose["docker-compose.yml"]
    click DockerCompose "https://github.com/starptech/go-web/blob/master/docker-compose.yml"

    %% Flows
    ClientUI -->|"HTTP Requests"| Server
    Parcel --> AppJS
    Parcel --> IndexJS
    Parcel --> Header
    Parcel --> LikeBtn
    Parcel --> StylesApp
    AppJS --> GlobalHTML
    GlobalIndex --> Header
    GlobalStyles -.-> StylesApp
    Server --> Cockroach
    Server --> Redis
    DockerCompose --> Cockroach
    DockerCompose --> Redis
    Entry --> GoWorkflow
    GoWorkflow --> ReleaseWorkflow
    ReleaseWorkflow --> Makefile

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef server fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
