# saxenabhishek/pulse architecture

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

- Interactive diagram: https://gitdiagram.com/saxenabhishek/pulse
- Repository: https://github.com/saxenabhishek/pulse

## Overview

##### Project Type and Purpose
- This is a full-stack “Newspaper” application named **pulse**.
- Frontend: a React + TypeScript SPA built with Vite (in the **client** folder).
- Backend: a Go HTTP server exposing REST endpoints for news and IP lookup (in the **server** folder).

##### File Structure Analysis
- **client/**
- src/service/news.tsx → defines functions like `fetchLatestNews()` that call `/api/news`.
- src/service/mocks.tsx → mock implementations of the same API calls.
- src/components → UI components (Article, ContentSection, Header, Footer, etc.).
- Vite config, tsconfig, .env for dev/prod.
- **server/**
- controller.go → HTTP handlers (e.g., `GetNewsHandler`, `GetIPHandler`).
- internal/news/news.go → business logic function `GetLatestNews()`.
- internal/ip/ip.go → function `GetClientIP()`.
- internal/common/common.go → shared utilities.
- main.go → routes setup:
– `http.HandleFunc("/api/news", GetNewsHandler)`
– `http.HandleFunc("/api/ip", GetIPHandler)`

##### Key Architectural Patterns
- Controller-Service separation:
– Handlers in `controller.go` delegate to `internal/...` packages.
- Clear API boundary: frontend uses a thin service layer (`fetchLatestNews()`, `fetchClientIP()`).
- Environment-based configs via Vite `.env` files and Go’s module system.

##### Main System Components
a. **Frontend (Browser)**
- Components: Header, Content, Article, Footer
- Service Layer:
- `fetchLatestNews()` → calls GET /api/news
- `fetchClientIP()` → calls GET /api/ip
b. **API Gateway / Controller (Go HTTP Server)**
- `GetNewsHandler(w, r)`
- `GetIPHandler(w, r)`
c. **Business Logic Services**
- `news.GetLatestNews()` → encapsulates logic to fetch or aggregate news
- `ip.GetClientIP()` → extracts client IP from request
- `common` utilities for error handling, logging, etc.
d. **External Systems (if any)**
- Third-party news APIs or databases (not explicitly in code, but implied)

##### Interactions & Data Flow
1. User interacts with UI → triggers a component (e.g., `Content`) to call `fetchLatestNews()`.
2. `fetchLatestNews()` issues HTTP GET to `/api/news`.
3. Go server’s `GetNewsHandler` receives request → calls `internal/news.GetLatestNews()`.
4. `GetLatestNews()` fetches data (mock, file system, or external API) → returns JSON.
5. Handler writes JSON response → frontend component receives and renders articles.
6. Similar flow for IP lookup via `/api/ip` → `GetIPHandler` → `internal/ip.GetClientIP()`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Browser
    subgraph "Frontend (Browser)"
        direction TB
        subgraph "UI Components"
            direction TB
            Header["Header"]:::frontend
            Content["Content"]:::frontend
            Article["Article"]:::frontend
            Footer["Footer"]:::frontend
        end
        subgraph "Service Layer"
            direction TB
            fetchLatestNews["fetchLatestNews()"]:::frontend
            fetchClientIP["fetchClientIP()"]:::frontend
            Mocks["mocks.tsx"]:::frontend
        end
    end

    %% Backend Controllers
    subgraph "API Gateway / Controllers"
        direction TB
        GetNewsHandler["GetNewsHandler"]:::controller
        GetIPHandler["GetIPHandler"]:::controller
        Main["main.go (route setup)"]:::controller
    end

    %% Business Logic Services
    subgraph "Business Logic Services"
        direction TB
        NewsService["GetLatestNews()"]:::business
        IPService["GetClientIP()"]:::business
        CommonUtils["common.go"]:::business
    end

    %% External Systems
    ExternalAPI["External News API"]:::external

    %% Connections
    Header -->|calls| fetchLatestNews
    Content -->|calls| fetchLatestNews
    Article -->|calls| fetchLatestNews
    Footer -->|calls| fetchClientIP

    fetchLatestNews -->|"GET /api/news"| GetNewsHandler
    fetchClientIP -->|"GET /api/ip"| GetIPHandler

    GetNewsHandler -->|"calls"| NewsService
    GetIPHandler -->|"calls"| IPService

    NewsService -->|fetches data from| ExternalAPI
    IPService -->|uses| CommonUtils

    Main --> GetNewsHandler
    Main --> GetIPHandler

    %% Click Events
    click Header "https://github.com/saxenabhishek/pulse/blob/main/client/src/components/Header.tsx"
    click Content "https://github.com/saxenabhishek/pulse/blob/main/client/src/components/Content.tsx"
    click Article "https://github.com/saxenabhishek/pulse/blob/main/client/src/components/Article.tsx"
    click Footer "https://github.com/saxenabhishek/pulse/blob/main/client/src/components/Footer.tsx"
    click fetchLatestNews "https://github.com/saxenabhishek/pulse/blob/main/client/src/service/news.tsx"
    click fetchClientIP "https://github.com/saxenabhishek/pulse/blob/main/client/src/service/news.tsx"
    click Mocks "https://github.com/saxenabhishek/pulse/blob/main/client/src/service/mocks.tsx"
    click GetNewsHandler "https://github.com/saxenabhishek/pulse/blob/main/server/controller.go"
    click GetIPHandler "https://github.com/saxenabhishek/pulse/blob/main/server/controller.go"
    click Main "https://github.com/saxenabhishek/pulse/blob/main/server/main.go"
    click NewsService "https://github.com/saxenabhishek/pulse/blob/main/server/internal/news/news.go"
    click IPService "https://github.com/saxenabhishek/pulse/blob/main/server/internal/ip/ip.go"
    click CommonUtils "https://github.com/saxenabhishek/pulse/blob/main/server/internal/common/common.go"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#027AFF,color:#000;
    classDef controller fill:#DFFFE0,stroke:#28A745,color:#000;
    classDef business fill:#FFE6C3,stroke:#FF8C00,color:#000;
    classDef external fill:#E0E0E0,stroke:#999,color:#000;
```
