# pakkudon/good-feeds architecture

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

- Interactive diagram: https://gitdiagram.com/pakkudon/good-feeds
- Repository: https://github.com/pakkudon/good-feeds

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Good Feeds”) that helps users discover places to eat or drink around Melbourne.
- The backend (“api” directory) is a Go service exposing a REST API and performing database migrations against a MySQL server.
- The frontend (“client” directory) is a Next.js (React) app, statically generated and served (e.g., GitHub Pages), which consumes the backend API.

##### File Structure
- Top-level directories:
- api – Go modules, handlers, models, repositories, database migrations, main entry point.
- client – Next.js code (`src/app`, components, configuration), styling (Tailwind), static assets (`public`).
- Notice the separation: “api” contains business logic and persistence; “client” holds UI and presentation.
- Migrations under `api/db/migrations` drive schema evolution (MySQL).
- ADRs document key architectural choices: relational DB, Go on server, Next.js front-end, static site generation.

##### Extract Insights from the README
- Backend uses Go 1.21, MySQL, runs migrations via `cmd/migrate.go`, and starts the API server in `main.go`.
- Frontend uses Node.js v20+, Next.js, and static generation (`npm run dev` for local).
- The public site is hosted at GitHub Pages (static assets).

##### Main Components & Their Roles
a. Client-Side (Next.js)
- Static Host/CDN (e.g., GitHub Pages) serving HTML/CSS/JS.
- React components calling backend REST endpoints (`/restaurants`, `/options`).
b. API Server (Go)
- HTTP router/handlers (`api/handler/*.go`).
- Business logic & validation.
- Repository layer (`api/repository/*.go`) interacting with MySQL via models (`api/model/*.go`).
- Migration tool (`api/cmd/migrate.go`) applying SQL scripts (`api/db/migrations`).
c. Database
- MySQL instance holding tables for restaurants, options, dietary options, etc.
- Migration scripts manage schema versioning.
d. External Services
- (If used) Map API or geocoding service invoked by the client for map display.

##### Relationships and Data Flow
1. User’s Browser → CDN/Static Host → Serves Next.js static pages & assets.
2. Browser (React app) → HTTP REST calls → Go API endpoints.
3. Go Handler → Repository → MySQL → returns data to handler → JSON to client.
4. Migrations (one-time or CI/CD) ensure DB schema is up-to-date before server start.

##### Architectural Patterns & Principles
- Layered Architecture: Presentation (frontend), API (handlers), Business/Repository, Persistence (DB).
- Repository Pattern in Go for data access abstraction.
- ADRs for capturing high-level decisions.
- Static site generation for performance and cost-effective hosting.
- SQL migrations for deterministic schema management.

##### Technologies & Frameworks to Annotate
- Frontend: Next.js (React), TypeScript, Tailwind CSS, Node.js.
- Backend: Go modules, `net/http`, custom handlers, Go’s database/sql (MySQL driver).
- DB: MySQL, SQL migration scripts.
- CI/CD or hosting: GitHub Pages (frontend), Go deployment target for API, MySQL instance (self-hosted or cloud).

##### Final Checklist
[ ] Clear, consistent component labels
[ ] Notation of technologies & frameworks on or near each component
[ ] Migration flow illustrated from `cmd/migrate.go` → `db/migrations` → MySQL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User and CDN
    User["User Browser"]:::external
    CDN["GitHub Pages/CDN\n(Static Assets)"]:::infra

    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        FrontendApp["Next.js App\n(client/src/app)"]:::frontend
        Components["Frontend Components\n(client/src/components)"]:::frontend
        Layout["Layout & Page\n(client/src/app/layout.tsx,\nclient/src/app/page.tsx)"]:::frontend
        Tailwind["Tailwind CSS Config\n(client/tailwind.config.js)"]:::frontend
        StaticAssets["Static Config\n(client/public/.nojekyll)"]:::frontend
    end

    %% External Map Service
    ExternalMap["Map Service\n(e.g., Leaflet/Mapbox)"]:::external

    %% Backend Layer
    subgraph "Backend (Go API)" 
        API["API Server\n(api/main.go)"]:::backend
        GoMod["Dependencies\n(api/go.mod,\napi/go.sum)"]:::backend
        Handlers["HTTP Handlers\n(api/handler/restaurant.go,\napi/handler/option.go)"]:::backend
        Models["Business Models\n(api/model/restaurant.go,\napi/model/option.go)"]:::backend
        Repo["Repository Layer\n(api/repository/restaurant.go,\napi/repository/option.go)"]:::backend
        MigrationTool["Migration Tool\n(api/cmd/migrate.go)"]:::backend
        Migrations["DB Migrations\n(api/db/migrations)"]:::backend
    end

    %% Database
    DB["MySQL Database"]:::db

    %% Documentation
    subgraph "Documentation"
        DocsADR["ADRs\n(doc/architecture/decisions)"]:::infra
        DocsER["ER Diagram\n(doc/diagrams/entity-relationship-diagram.mmd)"]:::infra
    end

    %% Data Flows
    User -->|"Request HTML/CSS/JS"| CDN
    CDN --> FrontendApp
    FrontendApp -->|"HTTPS/JSON"| API
    FrontendApp --> Components
    FrontendApp --> Layout
    FrontendApp --> Tailwind
    FrontendApp --> StaticAssets
    FrontendApp -.->|"Mapping Data"| ExternalMap
    API --> GoMod
    API --> Handlers
    Handlers --> Repo
    Repo --> Models
    Models -->|"SQL"| DB
    MigrationTool -.-> Migrations
    Migrations -.->|"SQL Migrations"| DB

    %% Documentation Relations
    DocsADR --> API
    DocsER --> DB

    %% Click Events
    click FrontendApp "https://github.com/pakkudon/good-feeds/tree/main/client/src/app"
    click Components "https://github.com/pakkudon/good-feeds/tree/main/client/src/components"
    click StaticAssets "https://github.com/pakkudon/good-feeds/blob/main/client/public/.nojekyll"
    click Tailwind "https://github.com/pakkudon/good-feeds/blob/main/client/tailwind.config.js"
    click Layout "https://github.com/pakkudon/good-feeds/blob/main/client/src/app/layout.tsx"
    click Layout "https://github.com/pakkudon/good-feeds/blob/main/client/src/app/page.tsx"
    click API "https://github.com/pakkudon/good-feeds/blob/main/api/main.go"
    click GoMod "https://github.com/pakkudon/good-feeds/blob/main/api/go.mod"
    click GoMod "https://github.com/pakkudon/good-feeds/blob/main/api/go.sum"
    click Handlers "https://github.com/pakkudon/good-feeds/blob/main/api/handler/restaurant.go"
    click Handlers "https://github.com/pakkudon/good-feeds/blob/main/api/handler/option.go"
    click Models "https://github.com/pakkudon/good-feeds/blob/main/api/model/restaurant.go"
    click Models "https://github.com/pakkudon/good-feeds/blob/main/api/model/option.go"
    click Repo "https://github.com/pakkudon/good-feeds/blob/main/api/repository/restaurant.go"
    click Repo "https://github.com/pakkudon/good-feeds/blob/main/api/repository/option.go"
    click MigrationTool "https://github.com/pakkudon/good-feeds/blob/main/api/cmd/migrate.go"
    click Migrations "https://github.com/pakkudon/good-feeds/tree/main/api/db/migrations"
    click DocsADR "https://github.com/pakkudon/good-feeds/tree/main/doc/architecture/decisions"
    click DocsER "https://github.com/pakkudon/good-feeds/blob/main/doc/diagrams/entity-relationship-diagram.mmd"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E2F0D9,stroke:#22863a,color:#22863a;
    classDef db fill:#FFE8A1,stroke:#D29922,color:#8A3800;
    classDef infra fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef external fill:#F5E6FF,stroke:#6f42c1,color:#6f42c1
```
