# peterhhartmann/spac-9-frontend-integration architecture

> Architecture diagram of the GitHub repository peterhhartmann/spac-9-frontend-integration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peterhhartmann/spac-9-frontend-integration
- Repository: https://github.com/peterhhartmann/spac-9-frontend-integration

## Overview

##### Project type and purpose
- This is a full-stack monorepo exercise (“SPAC – Week 9 – Frontend-Integration”) that demonstrates a simple quotes application.
- Backend: Go gRPC server (using Entgo ORM + PostgreSQL), seeded with movie/quote data.
- Frontend: React + TypeScript SPA (Vite) communicating over gRPC-Web.
- Envoy Proxy: Bridges HTTP/1.1 (browser) to HTTP/2 (gRPC server).
- Database: PostgreSQL for persistence.

##### File structure
- Top-level:
- Dockerfiles (api, client, envoy) + docker-compose.yml
- /api: Go service, ent schema, migrations, gRPC server code, storage/seed
- /client: React SPA with TypeScript, gRPC-Web client, React-Query, UI components
- /proto & api/proto: shared and generated protobuf definitions
- Taskfile.yml and Taskfile under /api and /client for local automation
- Patterns:
- Monorepo separated into “client” and “api” directories
- Entgo for ORM, codegen of entity methods
- Buf + protoc code generation for API contracts
- Envoy as sidecar/proxy for protocol translation

##### Key insights from README
- Communication strictly via Protocol Buffers & gRPC for type safety
- Emphasis on frontend/backend integration rather than production readiness
- Use of Docker Compose (or Task) to orchestrate all services

##### Detail & granularity
- Following sub-components:
- Client: UI layer vs data-fetch layer (React-Query, gRPC-Web client)
- Server: gRPC server entrypoint, Entgo schema/migrations, storage seed
- Shared: Proto definitions repository, generated code output
- Build pipelines if relevant (e.g., Dockerfile-client → client image)
- Environmental configs ( .env.dev → docker-compose ) to illustrate how secrets/config flow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client" 
        direction TB
        ProtoSource["Proto Definitions"]:::artifact
        GenClient["Generated Client Protobuf Stubs"]:::artifact
        UI["UI Layer"]:::frontend
        Query["React-Query Layer"]:::frontend
        GRPCClient["gRPC-Web Client"]:::frontend
    end

    %% Proxy Layer
    subgraph "Proxy"
        direction TB
        Envoy["Envoy Proxy"]:::proxy
        EnvoyDocker["Dockerfile-envoy"]:::infra
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        GenServer1["Generated Server Protobuf (quotes.pb.go)"]:::artifact
        GenServer2["Generated Server Protobuf (quotes_grpc.pb.go)"]:::artifact
        ServerMain["Go Server Main"]:::backend
        GRPCServer["gRPC Server Entrypoint"]:::backend
        EntSchema["Entgo Schema Definitions"]:::backend
        EntGen["Entgo Generated Entities"]:::backend
        Migrations["Entgo Migrations"]:::backend
        MigrateGo["Migration Runner"]:::backend
        StorageConn["DB Connection"]:::backend
        StorageSeed["DB Seed"]:::backend
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerClient["Dockerfile-client"]:::infra
        DockerServer["Dockerfile-api"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        Postgres["PostgreSQL"]:::database
    end

    %% Dataflow
    ProtoSource --> GenClient
    ProtoSource --> GenServer1
    ProtoSource --> GenServer2

    GenClient --> UI
    UI --> Query
    Query --> GRPCClient

    GRPCClient -->|"gRPC-Web over HTTP/1.1"| Envoy
    Envoy -->|"gRPC HTTP/2"| GRPCServer
    GRPCServer --> StorageConn
    StorageConn --> Postgres
    GRPCServer --> StorageSeed
    StorageSeed --> Postgres
    GRPCServer --> EntGen
    EntGen --> EntSchema
    EntSchema --> Migrations
    Migrations --> MigrateGo
    MigrateGo --> Postgres
    Postgres --> GRPCServer
    GRPCServer --> Envoy
    Envoy -->|"gRPC-Web response"| GRPCClient

    %% Orchestration
    DockerClient --> DockerCompose
    DockerServer --> DockerCompose
    EnvoyDocker --> DockerCompose
    DockerCompose --> UI
    DockerCompose --> GRPCServer
    DockerCompose --> Envoy
    DockerCompose --> Postgres

    %% Click Events
    click UI "https://github.com/peterhhartmann/spac-9-frontend-integration/tree/main/client/src/views"
    click Query "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/client/src/api/queryClient.ts"
    click GRPCClient "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/client/src/api/grpcClient.ts"
    click ProtoSource "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/proto/quotes.proto"
    click GenClient "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/client/src/proto/gen/quotes_pb.ts"
    click GenServer1 "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/proto/quotespb/quotes.pb.go"
    click GenServer2 "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/proto/quotespb/quotes_grpc.pb.go"
    click Envoy "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/envoy.yaml"
    click EnvoyDocker "https://github.com/peterhhartmann/spac-9-frontend-integration/tree/main/Dockerfile-envoy"
    click ServerMain "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/main.go"
    click GRPCServer "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/grpc/server.go"
    click EntSchema "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/ent/schema/*.go"
    click EntGen "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/ent/*.go"
    click Migrations "https://github.com/peterhhartmann/spac-9-frontend-integration/tree/main/api/ent/migrate/migrations"
    click MigrateGo "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/ent/migrate/migrate.go"
    click StorageConn "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/storage/connection.go"
    click StorageSeed "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/api/storage/seed.go"
    click DockerClient "https://github.com/peterhhartmann/spac-9-frontend-integration/tree/main/Dockerfile-client"
    click DockerServer "https://github.com/peterhhartmann/spac-9-frontend-integration/tree/main/Dockerfile-api"
    click DockerCompose "https://github.com/peterhhartmann/spac-9-frontend-integration/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085;
    classDef proxy fill:#d4edda,stroke:#155724;
    classDef backend fill:#fff3cd,stroke:#856404;
    classDef database fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef infra fill:#f8d7da,stroke:#721c24;
    classDef artifact fill:#e2f0d9,stroke:#0f5132;
```
