# tantin135777/a-web-forum architecture

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

- Interactive diagram: https://gitdiagram.com/tantin135777/a-web-forum
- Repository: https://github.com/tantin135777/a-web-forum

## Overview

This is a **small full-stack web application**: a **web forum** with **topics → posts → comments** plus **username-only authentication**. Architecturally it’s a classic **SPA frontend** (React/TypeScript) calling a **Go HTTP API** that persists to a **PostgreSQL database (Neon hosted)**. Sessions are managed via **HTTP-only cookies**, and write operations require auth (cookie session or `X-User` header), while reads are public.

- **Browser + SPA** boundary and routing/pages
- **API surface** and auth rules (public GET vs authenticated writes)
- **Session/cookie flow**
- **Database + migrations**
- **Environments** (dev ports, Vite proxying via `VITE_API_BASE`, Neon remote DB)

From the file tree:

##### Backend (Go)
- `main.go` → **HTTP server entrypoint**: routes/handlers, middleware (likely auth/session), listens on `:8080`.
- `db.go` → **DB connection pool** (Postgres). This is the backend’s persistence adapter.
- `migrations/0001_init.sql` → **schema definition** for topics/posts/comments/users/sessions (or similar).
- `go.mod`, `go.sum` → dependency graph (helps annotate: net/http, postgres driver, migration tooling if any).

##### Frontend (React + TS via Vite)
- `frontend/src/main.tsx` → SPA bootstrap.
- `frontend/src/App.tsx` → top-level router/layout composition.
- `frontend/src/pages/*` → page-level UI: `HomePage`, `LoginPage`, `TopicPage`, `PostPage` (these align well to user journeys).
- `frontend/src/api/client.ts` → single **API client abstraction** (base URL `VITE_API_BASE`).
- `frontend/src/components/Layout.tsx` → shared UI chrome/navigation.
- `frontend/src/types.ts` → shared data contracts (topics/posts/comments/user).
- `frontend/vite.config.ts`, `frontend/.env.local` → runtime configuration / API base.

##### External dependency
- **Neon Postgres** (hosted). Important: DB is not local; it’s an external cloud service.

This structure strongly suggests a **3-tier** picture (Client ↔ API ↔ DB) with a few important sub-components (Auth/session, migrations, API client).

##### What to include from README (constraints and runtime behavior)
- **Frontend**: `http://localhost:5173` (Vite dev server)
- **Backend**: `http://localhost:8080`
- **API base**: configured by `VITE_API_BASE`
- **Auth**:
- Login with username; user auto-created
- Session via **HTTP-only cookie**, `SameSite=Lax`
- **Write ops** require auth (cookie or `X-User`)
- **Read ops (GET)** public
- **Data model actions**:
- Topics: create/edit/delete (any logged-in user)
- Posts/comments: only authors can edit/delete
- DB is **Neon hosted** (external boundary)

##### React SPA
- API client (`src/api/client.ts`) as an internal module
##### Go API Server
- HTTP routing/handlers (main.go)
- DB access layer (`db.go`)
##### Postgres (Neon)
- Schema managed by `migrations/*.sql`

Relationships:
- SPA uses `api/client.ts` → calls API endpoints
- API server validates session/auth → executes CRUD → DB

**Goal:** express request lifecycle and auth rules.

- **HTTP Router / Handlers** (from `main.go`)
- Endpoints by resource:
- `/login` (or similar) → sets session cookie
- `/topics` → list/create/update/delete
- `/topics/{id}/posts` or `/posts` → create/list
- `/posts/{id}/comments` or `/comments` → create/list
- **Auth module**
- Session validation from cookie
- Alternative auth via `X-User`
- Authorization checks (topic editable by any logged-in; post/comment only by author)
- **DB Pool** (`db.go`)

- “Request → auth check → handler → SQL → response”
- “Login → create/find user → create session → Set-Cookie”

Inside **React SPA**:
- **App shell** (`App.tsx`, `Layout.tsx`)
- **Pages** (Home/Login/Topic/Post)
- **API client** (`api/client.ts`)
- **Types/contracts** (`types.ts`)

Data flow:
- Page → API client → fetch JSON → render
- Login page triggers login call; browser stores cookie automatically; subsequent writes include cookie

Explicitly annotate: “Cookie is HttpOnly, not readable by JS; browser attaches automatically.”

##### “Don’t overthink it”: maximize component separation (but keep it accurate)
To be very detailed for this repo without inventing nonexistent services, split into many components *within the two main processes*:

- Frontend: App shell, Pages, API client, Types, Styling/Theme
- Backend: Router, Handlers by resource, Auth/session middleware, Authorization policy, DB pool, SQL queries, Migration artifacts
- External: Neon Postgres

##### C4 Container (1 page): Vite SPA, Go API, DB, Migrations, Env config
3. **Backend Component (1 page)**: Router/handlers, auth/session, authorization rules, DB pool, entities
4. (Optional) **Frontend Component (1 page)**: pages → api client → backend, cookie behavior note

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 0 / Context
    %% =========================
    U["User (Browser)"]:::external

    subgraph "Client (Local Dev)"
        VITE["Vite Dev Server\nhttp://localhost:5173"]:::frontend
        SPA["React SPA (TS)\n(Runs in browser)"]:::frontend
    end

    subgraph "Server (Local Dev)"
        API["Go HTTP API Server\nhttp://localhost:8080"]:::backend
    end

    subgraph "External (Cloud)"
        NEON[("Neon Postgres\n(Hosted PostgreSQL)")]:::database
    end

    U -->|"GET SPA assets (HTML/JS/CSS)"| VITE
    VITE -->|"Serves bundle"| U
    U -->|"Runs SPA"| SPA

    SPA -->|"HTTP (JSON) via VITE_API_BASE"| API
    API -->|"SQL (Postgres) via connection pool"| NEON
    API -->|"Set-Cookie: session=…; HttpOnly; SameSite=Lax"| U

    NOTE_AUTH["Auth rules:\n- GET is public\n- POST/PUT/DELETE require session cookie or X-User\n- Post/Comment edit/delete only by author\n- Topic create/edit/delete by any logged-in user"]:::note
    API -.->|"enforces"| NOTE_AUTH

    NOTE_COOKIE["Cookie behavior:\n- HttpOnly (JS cannot read)\n- Browser auto-attaches on subsequent requests"]:::note
    SPA -.->|"relies on"| NOTE_COOKIE

    NOTE_DEV["Dev topology:\n- Frontend :5173\n- Backend :8080\n- Cookie + cross-origin considerations"]:::note
    VITE -.->|"ports"| NOTE_DEV
    API -.->|"ports"| NOTE_DEV

    %% =========================
    %% Frontend (Container -> Components)
    %% =========================
    subgraph "Frontend Components (React SPA)"
        MAIN["Bootstrap / Mount Root\n(main.tsx)"]:::frontendComp
        APP["App Shell + Router\n(App.tsx)"]:::frontendComp
        LAYOUT["Shared Layout / Nav\n(Layout.tsx)"]:::frontendComp

        subgraph "Pages"
            HOME["Home Page\n(Topics list)"]:::page
            LOGIN["Login Page\n(Username-only)"]:::page
            TOPIC["Topic Page\n(Topic → Posts)"]:::page
            POST["Post Page\n(Post → Comments)"]:::page
        end

        CLIENT["API Client\n(VITE_API_BASE)\n(client.ts)"]:::apiClient
        TYPES["Shared Types / Contracts\n(types.ts)"]:::types
        VCFG["Vite Config\n(vite.config.ts)"]:::config
    end

    MAIN -->|"mounts"| APP
    APP -->|"wraps"| LAYOUT
    APP -->|"routes to"| HOME
    APP -->|"routes to"| LOGIN
    APP -->|"routes to"| TOPIC
    APP -->|"routes to"| POST

    HOME -->|"fetch topics (GET)"| CLIENT
    TOPIC -->|"fetch topic/posts (GET)"| CLIENT
    POST -->|"fetch post/comments (GET)"| CLIENT
    LOGIN -->|"login (POST)"| CLIENT

    CLIENT -->|"HTTP (JSON)\n(reads + writes)"| API
    TYPES -.->|"used by"| HOME
    TYPES -.->|"used by"| TOPIC
    TYPES -.->|"used by"| POST
    TYPES -.->|"used by"| CLIENT

    VCFG -.->|"configures dev server\n+ base/proxy"| VITE
    VCFG -.->|"defines"| CLIENT

    %% =========================
    %% Backend (Container -> Components)
    %% =========================
    subgraph "Backend Components (Go API Server)"
        ROUTER["HTTP Router / Handlers\n(main.go)"]:::backendComp
        AUTH["Auth + Session Middleware\n(Cookie or X-User)"]:::auth
        POLICY["Authorization Policy\n(Topic vs Post/Comment rules)"]:::auth
        DBPOOL["DB Connection Pool\n(db.go)"]:::db
        QUERIES["SQL Queries / Persistence\n(Topics/Posts/Comments/Users/Sessions)"]:::db
        MOD["Module Graph\n(go.mod)"]:::meta
        SUM["Dependency Lockfile\n(go.sum)"]:::meta
    end

    API -->|"dispatch"| ROUTER
    ROUTER -->|"calls"| AUTH
    AUTH -->|"checks & annotates user"| POLICY
    POLICY -->|"allows/denies"| ROUTER

    ROUTER -->|"CRUD"| QUERIES
    QUERIES -->|"uses"| DBPOOL
    DBPOOL -->|"connects"| NEON

    MOD -.->|"build deps"| API
    SUM -.->|"verifies deps"| API

    %% =========================
    %% DB Migrations / Schema
    %% =========================
    subgraph "Database Schema Management"
        MIG["Migrations (SQL)\n0001_init.sql"]:::migration
        NOTE_SCHEMA["Schema includes:\nTopics, Posts, Comments,\nUsers, Sessions (or similar)"]:::note
    end

    MIG -.->|"applies schema"| NEON
    MIG -.->|"defines"| NOTE_SCHEMA

    %% =========================
    %% Docs / Runtime Notes
    %% =========================
    DOCS["Project Runtime Notes\n(README.md)"]:::doc
    FDOC["Frontend Notes\n(frontend/README.md)"]:::doc

    DOCS -.->|"documents ports/env/auth"| NOTE_DEV
    DOCS -.->|"documents auth rules"| NOTE_AUTH
    FDOC -.->|"documents frontend usage"| VITE

    %% =========================
    %% Click Events (from component mapping)
    %% =========================
    click ROUTER "https://github.com/tantin135777/a-web-forum/blob/main/main.go"
    click DBPOOL "https://github.com/tantin135777/a-web-forum/blob/main/db.go"
    click MIG "https://github.com/tantin135777/a-web-forum/blob/main/migrations/0001_init.sql"
    click MOD "https://github.com/tantin135777/a-web-forum/blob/main/go.mod"
    click SUM "https://github.com/tantin135777/a-web-forum/blob/main/go.sum"

    click MAIN "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/main.tsx"
    click APP "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/App.tsx"
    click LAYOUT "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/components/Layout.tsx"
    click HOME "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/pages/HomePage.tsx"
    click LOGIN "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/pages/LoginPage.tsx"
    click TOPIC "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/pages/TopicPage.tsx"
    click POST "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/pages/PostPage.tsx"
    click CLIENT "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/api/client.ts"
    click TYPES "https://github.com/tantin135777/a-web-forum/blob/main/frontend/src/types.ts"
    click VCFG "https://github.com/tantin135777/a-web-forum/blob/main/frontend/vite.config.ts"

    click DOCS "https://github.com/tantin135777/a-web-forum/blob/main/README.md"
    click FDOC "https://github.com/tantin135777/a-web-forum/blob/main/frontend/README.md"

    %% =========================
    %% Styles (color is critical)
    %% =========================
    classDef external fill:#f5f5f5,stroke:#616161,stroke-width:1.5px,color:#111
    classDef frontend fill:#d6ebff,stroke:#1e88e5,stroke-width:1.5px,color:#0b2a3d
    classDef frontendComp fill:#bfe0ff,stroke:#1e88e5,stroke-width:1.2px,color:#0b2a3d
    classDef page fill:#a8d4ff,stroke:#1565c0,stroke-width:1.2px,color:#0b2a3d
    classDef apiClient fill:#90caf9,stroke:#0d47a1,stroke-width:1.2px,color:#07233a
    classDef backend fill:#d6f5e3,stroke:#2e7d32,stroke-width:1.5px,color:#0f2a17
    classDef backendComp fill:#c2efcf,stroke:#2e7d32,stroke-width:1.2px,color:#0f2a17
    classDef auth fill:#ffe0b2,stroke:#ef6c00,stroke-width:1.5px,color:#3a2200
    classDef database fill:#e6ddff,stroke:#5e35b1,stroke-width:1.8px,color:#1e1242
    classDef db fill:#d9ccff,stroke:#5e35b1,stroke-width:1.2px,color:#1e1242
    classDef migration fill:#ede7f6,stroke:#673ab7,stroke-width:1.5px,color:#24104a,stroke-dasharray: 6 4
    classDef config fill:#fff9c4,stroke:#f9a825,stroke-width:1.2px,color:#3a2f00
    classDef types fill:#c8e6c9,stroke:#388e3c,stroke-width:1.2px,color:#0f2a17
    classDef meta fill:#eceff1,stroke:#546e7a,stroke-width:1.2px,color:#102027
    classDef note fill:#ffffff,stroke:#9e9e9e,stroke-width:1px,color:#111,stroke-dasharray: 4 3
    classDef doc fill:#f3e5f5,stroke:#8e24aa,stroke-width:1.2px,color:#2a0d33
```
