# tsukunea1/git_feed architecture

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

- Interactive diagram: https://gitdiagram.com/tsukunea1/git_feed
- Repository: https://github.com/tsukunea1/git_feed

## Overview

##### Project Type and Purpose
- This is a full-stack, API-driven web application (“GitFeed”) that aggregates GitHub events and provides a Twitter-like feed for software engineers.
- The frontend is a Next.js + TypeScript + Tailwind UI app.
- The backend is a Ruby on Rails (API mode) monolith exposing a JSON REST API, persisting to PostgreSQL, and running scheduled background jobs to fetch GitHub events.

##### High-Level Architecture Components
A. Frontend (Next.js App)
- Renders UI, handles routing (App Router), state (Zustand), styling (Tailwind + shadcn/ui).
- Communicates with Backend API via HTTP (fetch/axios).
- Consumes OpenAPI-generated client (orval) to type-safe calls.
B. Backend API (Rails)
- Controllers → Services → Models (ActiveRecord)
- Auth layer: GitHub OAuth → JWT issuance (jwt_service.rb), stored in Redis/cookies.
- Background jobs (ActiveJob) for GitHub event fetching:
– Scheduler (cron or Taskfile) enqueues fetch jobs
– Job workers dequeue and call GitHub REST API (with ETag / If-Modified-Since)
– Upsert into `github_events`, tag assignment, update cursor
- Exposes REST endpoints (e.g., /api/v1/languages, /api/v1/user_tag_prefs)
- Uses PostgreSQL for data and possibly Redis/Sidekiq or DelayedJob for queueing (config/queue.yml)
C. Data Stores
- PostgreSQL: users, posts/likes/follows, subscriptions, events, tags, preferences.
- (Optional) Redis: queue adapter for background jobs & caching.
D. External Services
- GitHub REST API: fetch events & OAuth.
- (Planned) OpenAI GPT-3.5: profile analysis, AI chat.

##### Relationships & Data Flows
- User → Frontend (browser)
- Frontend → Backend API (request/response JSON)
- Backend → PostgreSQL (read/write)
- Backend Scheduler → Job Queue → GitHub API → Backend → Database
- (Future) Backend → OpenAI API → Database → Frontend

##### Architectural Patterns & Design Principles
- API-First: OpenAPI schema in `schema/openapi.yaml` generates client/server stubs.
- MVC on the backend, with a clear service-layer for business logic (e.g., EventFetcher, RepositorySearcher).
- Single-Page/Server-Rendered Hybrid on the frontend (Next.js App Router).
- Containerization: Dockerfile in each service + docker-compose.yml for local orchestration.
- CI/CD: GitHub Actions workflows for frontend, backend, and full pipeline.
- Task runner (Taskfile.yml) unifies local dev, linting, formatting, and hooks.

##### Must-Include
- Annotations for major technologies (Next.js, Rails, PostgreSQL, Sidekiq/ActiveJob, GitHub API, OpenAI).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend Styles
    classDef frontend fill:#e0ffe0,stroke:#2d862d,stroke-width:2px
    classDef backend fill:#e0e0ff,stroke:#2d3380,stroke-width:2px
    classDef db fill:#ffffcc,stroke:#997f02,stroke-width:2px,shape:cylinder
    classDef queue fill:#ffe0cc,stroke:#cc6600,stroke-width:2px
    classDef external fill:#f0f0f0,stroke:#666666,stroke-width:2px

    %% External Browser
    Browser["Browser (User)"]:::external

    %% Frontend Container
    subgraph "Next.js Frontend (port 3001)" 
        direction TB
        AppRouter["Pages & App Router"]:::frontend
        FeedPage["Feed Page"]:::frontend
        SignInPage["Sign-In Page"]:::frontend
        AuthSuccess["OAuth Success Page"]:::frontend
        AuthError["OAuth Error Page"]:::frontend
        ProfilePage["User Profile Page"]:::frontend
        SettingsPage["Settings Page"]:::frontend
        PopularLangs["Popular Languages Page"]:::frontend
        TagSelect["Tag Select Page"]:::frontend
        APIClient["API Client (orval)"]:::frontend
        StateStore["State Management (Zustand)"]:::frontend
        UIComponents["UI Component Library (shadcn/ui + custom)"]:::frontend
        GlobalConfig["Global Styles & Config"]:::frontend
    end

    %% Backend Container
    subgraph "Rails API Backend (port 3000)"
        direction TB
        HTTP["HTTP Layer (Controllers)"]:::backend
        Services["Service Layer"]:::backend
        Models["ActiveRecord Models"]:::backend
        Jobs["Background Jobs (ActiveJob)"]:::backend
        AuthInit["Auth Initialization"]:::backend
        Routing["Routing & Middleware"]:::backend
    end

    %% Data Stores and Queues
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL"]:::db
    end

    subgraph "Queue & Scheduler"
        direction TB
        Scheduler["Scheduler (cron/Taskfile)"]:::queue
        Queue["Job Queue / Worker Pool"]:::queue
    end

    %% External Services
    GitHubAPI["GitHub REST API"]:::external
    OpenAIAPI["OpenAI GPT-3.5 API"]:::external

    %% Orchestration and Config
    DockerCompose["Docker Compose"]:::external
    OpenAPISpec["OpenAPI Spec"]:::external

    %% Connections
    Browser -->|"HTTP Requests"| AppRouter
    AppRouter -->|"fetch JSON"| HTTP
    HTTP -->|"read/write"| Postgres
    HTTP -->|"enqueue jobs"| Queue
    Scheduler -->|"enqueue fetch jobs"| Queue
    Queue -->|"process jobs"| Jobs
    Jobs -->|"call REST"| GitHubAPI
    Jobs -->|"upsert events"| Postgres
    HTTP -->|"calls"| OpenAIAPI
    OpenAIAPI -->|"analysis results"| Postgres
    AppRouter -->|"<-/-> State/Props"| StateStore
    AppRouter -->|"type-safe calls"| APIClient
    AppRouter -->|"<-> UI"| UIComponents
    AppRouter -->|uses| GlobalConfig

    Browser --> AppRouter

    %% Orchestration Links
    DockerCompose --- AppRouter
    DockerCompose --- HTTP
    OpenAPISpec --- APIClient

    %% Click Events Frontend
    click AppRouter "https://github.com/tsukunea1/git_feed/tree/main/frontend/src/app"
    click FeedPage "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/feed/page.tsx"
    click SignInPage "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/signin/page.tsx"
    click AuthSuccess "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/auth/success/page.tsx"
    click AuthError "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/auth/error/page.tsx"
    click ProfilePage "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/[username]/page.tsx"
    click SettingsPage "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/settings/page.tsx"
    click PopularLangs "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/popular-langs/page.tsx"
    click TagSelect "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/tagselect/page.tsx"
    click APIClient "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/lib/api/generated.ts"
    click StateStore "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/stores/auth-store.ts"
    click UIComponents "https://github.com/tsukunea1/git_feed/tree/main/frontend/src/components/ui"
    click GlobalConfig "https://github.com/tsukunea1/git_feed/blob/main/frontend/src/app/globals.css"
    click GlobalConfig "https://github.com/tsukunea1/git_feed/blob/main/frontend/next.config.ts"
    click GlobalConfig "https://github.com/tsukunea1/git_feed/blob/main/frontend/postcss.config.mjs"

    %% Click Events Backend
    click HTTP "https://github.com/tsukunea1/git_feed/blob/main/backend/app/controllers/api/v1/languages_controller.rb"
    click Services "https://github.com/tsukunea1/git_feed/blob/main/backend/app/services/event_fetcher.rb"
    click Models "https://github.com/tsukunea1/git_feed/blob/main/backend/app/models/user.rb"
    click Jobs "https://github.com/tsukunea1/git_feed/blob/main/backend/app/jobs/application_job.rb"
    click AuthInit "https://github.com/tsukunea1/git_feed/blob/main/backend/config/initializers/omniauth.rb"
    click Routing "https://github.com/tsukunea1/git_feed/blob/main/backend/config/routes.rb"
    click Queue "https://github.com/tsukunea1/git_feed/blob/main/backend/config/queue.yml"
    click Scheduler "https://github.com/tsukunea1/git_feed/blob/main/Taskfile.yml"
    click Postgres "https://github.com/tsukunea1/git_feed/blob/main/backend/db/schema.rb"
    click DockerCompose "https://github.com/tsukunea1/git_feed/blob/main/docker-compose.yml"
    click OpenAPISpec "https://github.com/tsukunea1/git_feed/blob/main/schema/openapi.yaml"

    %% Classes
    class AppRouter,FeedPage,SignInPage,AuthSuccess,AuthError,ProfilePage,SettingsPage,PopularLangs,TagSelect,APIClient,StateStore,UIComponents,GlobalConfig frontend
    class HTTP,Services,Models,Jobs,AuthInit,Routing backend
    class Postgres db
    class Queue,Scheduler queue
    class GitHubAPI,OpenAIAPI,DockerCompose,OpenAPISpec external
```
