# saini-prakhyat/fern-reporter architecture

> Architecture diagram of the GitHub repository saini-prakhyat/fern-reporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saini-prakhyat/fern-reporter
- Repository: https://github.com/saini-prakhyat/fern-reporter

## Overview

##### Project Type and Purpose
- Fern-Reporter is a Go-based API server (Gin framework) that captures, stores, and exposes Ginkgo test metadata.
- It provides REST/GraphQL HTTP endpoints, a gRPC interface, embedded HTML views, and integrates with an external React-based UI (Fern-UI).
- A PostgreSQL database holds historical test, suite, spec, project and tag data.

##### File Structure
- Top-level: Dockerfiles, docker-compose.yaml, Makefile, config/.
- pkg/api: HTTP routers → handlers → server setup.
- pkg/graph: GraphQL schema, resolvers (gqlgen).
- grpcstart + grpcfiles/: gRPC server bootstrap and proto definitions.
- pkg/db: Database connection, migrations.
- pkg/auth: JWT middleware.
- pkg/views: Embedded HTML templates (insights.html, test_runs.html).
- config/: YAML/Go code for environment configuration.
- Main.go: entrypoint launching HTTP and gRPC servers.

##### README
- Describes two main components: API Server & Client Library.
- Lists endpoints: HTTP (port 8080), gRPC (port 50051), GraphiQL UI.
- Mentions Docker Compose with PostgreSQL.
- References external React frontend (Fern-UI).

a. Main Components
- Ginkgo Client (in a test suite)
- Fern-Reporter Service:
- HTTP API (Gin) → REST + GraphQL
- gRPC Server
- Embedded HTML Views
- Auth Middleware
- Config Loader
- PostgreSQL Database
- Fern-UI (React Frontend)

b. Interactions
- Ginkgo tests → send test metadata (HTTP POST or gRPC) → Fern Service
- Fern Service validates JWT (middleware) → writes/reads to PostgreSQL (pkg/db)
- GraphQL endpoint for ad-hoc queries (GraphiQL)
- HTTP endpoint serves embedded HTML at /reports/testruns
- Fern-UI queries REST/GraphQL for dashboards
- Docker Compose orchestrates Fern Service + Postgres

c. Architectural Patterns
- Layered MVC-style backend: routers → handlers → business logic → data layer
- Schema-first GraphQL generated by gqlgen
- Dual-protocol API (REST/GraphQL + gRPC)
- Environment-based configuration (config package + .yaml)

d. Key Technologies
- Go + Gin framework (HTTP)
- gqlgen (GraphQL)
- gRPC + protobuf
- PostgreSQL + Goose-style migrations
- Docker, Docker Compose
- JWT authentication

##### Essential Elements Checklist
- Component names & roles (API Server, gRPC Server, Auth Middleware, DB)
- Data flows and directions
- Protocols and ports
- External dependencies (Docker Compose, Fern-UI, Ginkgo client)
- Config/migrations path (config/, pkg/db/migrations)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Ginkgo["Ginkgo Client"]:::external
    UI["Fern-UI (React Frontend)"]:::external

    %% Docker Compose Container
    subgraph "Docker Compose Orchestration"
        direction TB
        subgraph "Fern-Reporter Service"
            direction TB

            Config["Config Loader\n(config/config.go)"]:::service
            Auth["JWT Auth Middleware\n(pkg/auth/middleware.go)"]:::service
            subgraph "API Layer"
                direction TB
                HTTPServer["HTTP API (Gin)\n(port 8080)"]:::service
                Handlers["REST Handlers"]:::service
                GraphQL["GraphQL API\n(port 8080)"]:::service
            end
            subgraph "gRPC Layer"
                direction TB
                GRPCStart["gRPC Bootstrap"]:::service
                Proto["gRPC Services\n(proto definitions)"]:::service
            end
            subgraph "Data Layer"
                direction TB
                DBConn["DB Connection\n(pkg/db/db.go)"]:::service
                Migrations["Migrations\n(pkg/db/migrations)"]:::service
                Models["Data Models\n(pkg/models/types.go)"]:::service
            end
            Views["Embedded HTML Views"]:::service
            Main["Main Entrypoint\n(main.go)"]:::service
        end

        Postgres["PostgreSQL Database\n(port 5432)"]:::db
    end

    %% Interactions
    Ginkgo -->|REST/gRPC| HTTPServer
    Ginkgo -->|gRPC| GRPCStart
    UI -->|REST| HTTPServer
    UI -->|GraphQL| GraphQL
    HTTPServer -->|uses| Auth
    GraphQL -->|uses| Auth
    HTTPServer -->|calls| Handlers
    GraphQL -->|resolves| GraphQL
    GRPCStart -->|initializes| Proto
    Auth -->|validates| DBConn
    Handlers -->|SQL| DBConn
    Proto -->|SQL| DBConn
    DBConn -->|runs| Migrations
    DBConn -->|maps| Models
    Views -->|served by| HTTPServer
    HTTPServer -->|read/write| Postgres
    GRPCStart -->|read/write| Postgres
    GraphQL -->|read/write| Postgres

    %% Click Events
    click HTTPServer "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/api/server.go"
    click Handlers "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/api/handlers/handlers.go"
    click Config "https://github.com/saini-prakhyat/fern-reporter/blob/main/config/config.go"
    click Auth "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/auth/middleware.go"
    click GraphQL "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/graph/graphql.go"
    click GraphQL "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/graph/resolvers/schema.resolvers.go"
    click GraphQL "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/graph/schemas/schema.graphql"
    click GraphQL "https://github.com/saini-prakhyat/fern-reporter/blob/main/gqlgen.yml"
    click GRPCStart "https://github.com/saini-prakhyat/fern-reporter/blob/main/grpcstart/grpc_server.go"
    click GRPCStart "https://github.com/saini-prakhyat/fern-reporter/blob/main/grpcstart/grpcstart.go"
    click Proto "https://github.com/saini-prakhyat/fern-reporter/tree/main/grpcfiles/"
    click DBConn "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/db/db.go"
    click Migrations "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/db/migrations/000001_create_test_run_table.up.sql"
    click Views "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/views/insights.html"
    click Views "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/views/test_runs.html"
    click Main "https://github.com/saini-prakhyat/fern-reporter/blob/main/main.go"
    click Models "https://github.com/saini-prakhyat/fern-reporter/blob/main/pkg/models/types.go"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#4A90E2,stroke-width:1px
    classDef external fill:#E0F8E0,stroke:#2E8B57,stroke-width:1px
    classDef db fill:#FFE3B3,stroke:#FF8C00,stroke-width:1px
```
