# nycu-sdc/cli-forum architecture

> Architecture diagram of the GitHub repository nycu-sdc/cli-forum, 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/nycu-sdc/cli-forum
- Repository: https://github.com/nycu-sdc/cli-forum

## Overview

##### Project Type and Purpose
- CLI-Forum is a full-stack, two-component system comprised of:
a. A command-line interface client (“cli/”) for end users to interact with the forum.
b. A Go-based RESTful API backend (“backend/”) that manages users, posts, and comments and provides authentication, authorization, and observability.
- The backend uses OpenTelemetry (via Vector and Tempo) for logging, metrics, and traces.

##### File Structure
- Top-level components:
- `.github/` – CI/CD workflows for building, testing, and linting.
- `backend/` – Go REST API server, internal business logic, database migrations, OpenAPI spec, observability configs.
- `cli/` – Go-based CLI client that calls the backend API.
- `backend/internal/` contains layered subpackages:
- `auth`, `jwt` – authentication and JWT middleware.
- `user`, `post`, `comment` – domain logic with models, SQL queries (via sqlc), service and handler layers.
- `database` – migration scripts and full schema builder.
- `middleware.go`, `logger.go`, `validator.go` – cross-cutting concerns.
- `observe/` – Docker-Compose file orchestrating Vector (logs), Tempo (traces), etc.
- Configuration files: `config.yaml`, `openapi.yaml`, `sqlc.yaml`, Dockerfiles, Makefiles.

##### README Insights
- RESTful API endpoints for user auth, post and comment CRUD.
- CLI uses those endpoints over HTTP.
- Observability integration for logging/tracing.
- Best practices, experimentation, and learning.

##### Components
a. CLI Application
- Shows: `cli/main.go` invokes HTTP calls
b. API Gateway / Backend Service
- HTTP Server (OpenAPI-generated router)
- Middleware chain: Logger → Auth/JWT → Validator → Error Handler
- Domain Services: UserService, PostService, CommentService
- Database Layer: sqlc-generated stores, migrations
c. Database
- Contains: user, post, comment tables (migrations in `backend/internal/database/migrations/`)
d. Observability Stack
- Sub-components: Vector (logs), Tempo (traces) configured by `backend/observe/`
e. External Systems (if any)
- E.g., Docker daemon, CI/CD pipeline (.github) – optional high-level note

##### Architectural Patterns and Design Principles
- Layered architecture in `backend/internal/`:
- Transport (handlers) → Service → Store → Database
- Separation of concerns: middleware, business logic, data access
- Configuration-as-code: YAML for OpenAPI, sqlc, Docker-Compose, app config
- Test coverage: handler tests in `internal/post` and `internal/comment`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "CLI-Forum Client"
        CLIClient["CLI-Forum Client"]:::client
        CLIMain["main.go"]:::client
        CLIMake["Makefile"]:::client
        CLIMod["go.mod"]:::client
    end

    %% Backend Service
    subgraph "Go REST API" 
        BackendEntry["main.go"]:::service
        ConfigYaml["config.yaml"]:::service
        OpenAPI["openapi.yaml"]:::service
        BackendMake["Makefile"]:::service
        BackendDocker["Dockerfile"]:::service

        subgraph "Transport & Routing"
            HTTPHandler["handler.go"]:::service
        end
        subgraph "Middleware Chain"
            Logger["logger.go"]:::service
            Middleware["middleware.go"]:::service
            AuthMiddleware["auth/middleware.go"]:::service
            JWTMiddleware["jwt/middleware.go"]:::service
            Validator["validator.go"]:::service
        end
        subgraph "Domain Services"
            UserService["user/service.go"]:::service
            UserHandler["user/handler.go"]:::service
            PostService["post/service.go"]:::service
            PostHandler["post/handler.go"]:::service
            CommentService["comment/service.go"]:::service
            CommentHandler["comment/handler.go"]:::service
            ErrorDefs["error/errors.go"]:::service
        end
        subgraph "Data Access Layer"
            UserDB["user/db.go"]:::service
            PostDB["post/db.go"]:::service
            CommentDB["comment/db.go"]:::service
        end
    end

    %% Database
    subgraph "PostgreSQL" 
        Migrations["migrations/"]:::datastore
        FullSchema["full_schema.sql"]:::datastore
        DBErrors["errors.go"]:::datastore
    end

    %% Observability
    subgraph "OpenTelemetry Collector"
        ObsCompose["docker-compose.yml"]:::obs
        VectorCfg["vector.toml"]:::obs
        TempoCfg["tempo.yaml"]:::obs
    end

    %% CI/CD (External)
    subgraph "CI/CD Pipeline"
        GHMain["main.yml"]:::external
        GHPull["pull_request.yml"]:::external
    end

    %% Relationships
    CLIClient -->|HTTP/JSON| HTTPHandler
    HTTPHandler -->|chain calls| Logger
    Logger -->|→| AuthMiddleware
    AuthMiddleware -->|→| JWTMiddleware
    JWTMiddleware -->|→| Validator
    Validator -->|validated| UserService
    Validator -->|validated| PostService
    Validator -->|validated| CommentService
    UserService -->|uses| UserDB
    PostService -->|uses| PostDB
    CommentService -->|uses| CommentDB
    UserDB -->|SQL| Migrations
    PostDB -->|SQL| Migrations
    CommentDB -->|SQL| Migrations
    HTTPHandler -->|reads config| ConfigYaml
    HTTPHandler -->|OpenAPI spec| OpenAPI
    HTTPHandler -->|build image| BackendDocker
    HTTPHandler -->|make tasks| BackendMake
    HTTPHandler -->|app start| BackendEntry
    HTTPHandler -->|errors| ErrorDefs
    HTTPHandler -->|OTLP| ObsCompose
    HTTPHandler -->|OTLP| VectorCfg
    HTTPHandler -->|OTLP| TempoCfg

    %% CI/CD triggers build
    GHMain -->|CI build| BackendEntry
    GHPull -->|CI test| BackendEntry

    %% Click Events
    click CLIMain "https://github.com/nycu-sdc/cli-forum/blob/main/cli/main.go"
    click CLIMake "https://github.com/nycu-sdc/cli-forum/tree/main/cli/Makefile"
    click CLIMod "https://github.com/nycu-sdc/cli-forum/blob/main/cli/go.mod"

    click BackendEntry "https://github.com/nycu-sdc/cli-forum/blob/main/backend/cmd/backend/main.go"
    click ConfigYaml "https://github.com/nycu-sdc/cli-forum/blob/main/backend/config.yaml"
    click OpenAPI "https://github.com/nycu-sdc/cli-forum/blob/main/backend/openapi.yaml"
    click BackendMake "https://github.com/nycu-sdc/cli-forum/tree/main/backend/Makefile"
    click BackendDocker "https://github.com/nycu-sdc/cli-forum/tree/main/backend/Dockerfile"

    click HTTPHandler "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/handler.go"
    click Logger "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/logger.go"
    click Middleware "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/middleware.go"
    click AuthMiddleware "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/auth/middleware.go"
    click JWTMiddleware "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/jwt/middleware.go"
    click Validator "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/validator.go"

    click UserService "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/user/service.go"
    click UserHandler "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/user/handler.go"
    click PostService "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/post/service.go"
    click PostHandler "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/post/handler.go"
    click CommentService "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/comment/service.go"
    click CommentHandler "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/comment/handler.go"
    click ErrorDefs "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/error/errors.go"

    click UserDB "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/user/db.go"
    click PostDB "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/post/db.go"
    click CommentDB "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/comment/db.go"

    click Migrations "https://github.com/nycu-sdc/cli-forum/tree/main/backend/internal/database/migrations/"
    click FullSchema "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/database/full_schema.sql"
    click DBErrors "https://github.com/nycu-sdc/cli-forum/blob/main/backend/internal/database/errors.go"

    click ObsCompose "https://github.com/nycu-sdc/cli-forum/blob/main/backend/observe/docker-compose.yml"
    click VectorCfg "https://github.com/nycu-sdc/cli-forum/blob/main/backend/observe/vector.toml"
    click TempoCfg "https://github.com/nycu-sdc/cli-forum/blob/main/backend/observe/tempo.yaml"

    click GHMain "https://github.com/nycu-sdc/cli-forum/blob/main/.github/workflows/main.yml"
    click GHPull "https://github.com/nycu-sdc/cli-forum/blob/main/.github/workflows/pull_request.yml"

    %% Styles
    classDef client fill:#e0f7e9,stroke:#2ecc71,color:#2c3e50;
    classDef service fill:#e8f4fc,stroke:#3498db,color:#2c3e50;
    classDef datastore fill:#fdebd0,stroke:#e67e22,color:#2c3e50;
    classDef obs fill:#f3e5f5,stroke:#9b59b6,color:#2c3e50;
    classDef external fill:#ecf0f1,stroke:#95a5a6,color:#2c3e50;
```
