# madraka/gonews architecture

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

- Interactive diagram: https://gitdiagram.com/madraka/gonews
- Repository: https://github.com/madraka/gonews

## Overview

##### Project type and purpose
- GONews is a production-ready, open-source RESTful API written in Go. It exposes HTTP endpoints for article management, user authentication, AI-powered semantic search, real-time WebSocket updates, video processing, and background tasks. It is primarily a backend microservice with multiple entry points (API server, worker, CLI tools).

##### File structure
- Top-level “cmd/” contains distinct Go binaries:
- api (the HTTP/HTTPS server with Swagger docs)
- worker (background job processor)
- migrate, seed (database migration and data seeding)
- http2-test, latency-test (performance testing)
- “internal/” holds application code organized by layer:
- config, server, middleware, routes (HTTP layer)
- handlers (API handlers)
- services (business logic)
- repositories, database (persistence)
- cache, queue, pubsub (Redis-backed caching and job queue)
- storage (local/S3 file storage)
- auth, metrics, tracing, validators, profiling
- “deployments/” and “Dockerfiles” for Docker Compose and Kubernetes setups
- “monitoring/” with Prometheus, Grafana, OpenTelemetry configs
- “tests/” with unit, integration, E2E tests

##### README for additional insights
- Key external dependencies: PostgreSQL, Redis, Elasticsearch, OpenAI, S3 (or local)
- Observability: Prometheus metrics, Grafana dashboards, OpenTelemetry tracing, structured logging
- Deployment targets: Docker, Kubernetes, bare metal
- Features: WebSocket support, HTTP/2, JWT auth, role-based access

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        Web["Web/Mobile Apps"]:::client
        CLI["CLI Tools & Tests"]:::client
    end

    %% Ingress
    Web -->|HTTP/HTTPS| Ingress["Ingress (Cloudflare/In-Cluster)"]:::infra
    CLI -->|HTTP/HTTPS| Ingress

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        API["API Server (cmd/api)"]:::service
        Worker["Background Worker (cmd/worker)"]:::service
        Migrate["DB Migration CLI (cmd/migrate)"]:::service
        Seed["Data Seeding CLI (cmd/seed)"]:::service
        HTTP2Test["HTTP/2 Test CLI (cmd/http2-test)"]:::service
        LatencyTest["Latency Test CLI (cmd/latency-test)"]:::service

        Ingress --> API

        %% HTTP Layer
        API -->|"load config"| Config["Config (internal/config)"]:::component
        API -->|"start server"| Server["Server (internal/server)"]:::component
        API -->|"apply middleware"| Middleware["Middleware (internal/middleware)"]:::component
        API -->|"register routes"| Routes["Routes (internal/routes)"]:::component
        Routes --> Handlers["Handlers (internal/handlers)"]:::component

        %% Application Layers
        Handlers --> Services["Business Services (internal/services)"]:::component
        Services --> Repositories["Repositories (internal/repositories)"]:::component
        Services --> Database["Database Access (internal/database)"]:::component
        Services --> CacheLayer["Cache (internal/cache)"]:::component
        Services --> QueueComp["Queue (internal/queue)"]:::component
        QueueComp --> Processors["Processors (internal/queue/processors)"]:::component
        Services --> Pubsub["Pub/Sub (internal/pubsub)"]:::component
        Services --> Storage["Storage Adapters (internal/storage)"]:::component
        Services --> Auth["Auth (internal/auth)"]:::component
        Services --> Validators["Validators (internal/validators)"]:::component
        Services --> MetricsComp["Metrics (internal/metrics)"]:::component
        Services --> TracingComp["Tracing (internal/tracing)"]:::component
        Services --> Profiling["Profiling (internal/profiling)"]:::component
        Services --> VersionInfo["Version Info (internal/version)"]:::component

        %% Asynchronous Flow
        Services -.->|enqueue job| QueueComp
        QueueComp -->|consume| Worker
        Worker -->|process| Processors
        Worker -->|write| Database
        Worker -->|store outputs| Storage

        %% Data Stores
        Database --> Postgres["PostgreSQL"]:::db
        CacheLayer --> RedisCache["Redis (cache)"]:::db
        QueueComp --> RedisQueue["Redis (queue)"]:::db
        Services --> Elasticsearch["Elasticsearch"]:::db
        Services --> OpenAIExt["OpenAI API"]:::external
        Services --> S3Storage["S3 / Local FS"]:::db

        %% Observability
        API -->|export metrics/traces| OTEL["OTEL Collector"]:::obs
        Worker -->|export metrics/traces| OTEL
        OTEL --> Prometheus["Prometheus"]:::obs
        OTEL --> Grafana["Grafana"]:::obs
        OTEL --> Jaeger["Jaeger"]:::obs
    end

    %% Click Events
    click API "https://github.com/madraka/gonews/tree/main/cmd/api"
    click Worker "https://github.com/madraka/gonews/tree/main/cmd/worker"
    click Migrate "https://github.com/madraka/gonews/tree/main/cmd/migrate"
    click Seed "https://github.com/madraka/gonews/tree/main/cmd/seed"
    click HTTP2Test "https://github.com/madraka/gonews/tree/main/cmd/http2-test"
    click LatencyTest "https://github.com/madraka/gonews/tree/main/cmd/latency-test"
    click Config "https://github.com/madraka/gonews/tree/main/internal/config"
    click Server "https://github.com/madraka/gonews/tree/main/internal/server"
    click Middleware "https://github.com/madraka/gonews/tree/main/internal/middleware"
    click Routes "https://github.com/madraka/gonews/tree/main/internal/routes"
    click Handlers "https://github.com/madraka/gonews/tree/main/internal/handlers"
    click Services "https://github.com/madraka/gonews/tree/main/internal/services"
    click Repositories "https://github.com/madraka/gonews/tree/main/internal/repositories"
    click Database "https://github.com/madraka/gonews/tree/main/internal/database"
    click CacheLayer "https://github.com/madraka/gonews/tree/main/internal/cache"
    click QueueComp "https://github.com/madraka/gonews/tree/main/internal/queue"
    click Processors "https://github.com/madraka/gonews/tree/main/internal/queue/processors"
    click Pubsub "https://github.com/madraka/gonews/tree/main/internal/pubsub"
    click Storage "https://github.com/madraka/gonews/tree/main/internal/storage"
    click Auth "https://github.com/madraka/gonews/tree/main/internal/auth"
    click Validators "https://github.com/madraka/gonews/tree/main/internal/validators"
    click MetricsComp "https://github.com/madraka/gonews/tree/main/internal/metrics"
    click TracingComp "https://github.com/madraka/gonews/tree/main/internal/tracing"
    click Profiling "https://github.com/madraka/gonews/tree/main/internal/profiling"
    click VersionInfo "https://github.com/madraka/gonews/tree/main/internal/version"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef component fill:#F0F4C3,stroke:#7CB342,stroke-width:1px;
    classDef db fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,stroke-dasharray: 5 5;
    classDef infra fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,stroke-dasharray: 2 2;
    classDef client fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px;
    classDef obs fill:#FFCDD2,stroke:#E53935,stroke-width:1px;
```
