# ozblind/ozblind_fe architecture

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

- Interactive diagram: https://gitdiagram.com/ozblind/ozblind_fe
- Repository: https://github.com/ozblind/ozblind_fe

## Overview

##### Project type and purpose
- This is a single-page web application (SPA) frontend built with React, Vite, and TypeScript (“OZBLIND Frontend”).
- It provides UI for browsing and interacting with posts, notifications, jobs, bookmarks, and user settings. It communicates with backend REST APIs and several third-party services (e.g., GitHub API, remote job APIs).

##### File structure
- Top-level config: Docker Compose, Vite config, environment files, linting/config scripts.
- src/ layout:
- src/pages – route components (Page layer)
- src/router – route definitions and guards
- src/layouts – page wrappers (MainLayout, RootLayout)
- src/components – reusable UI pieces (Board, Post, Sidebar, Toast, etc.)
- src/api – HTTP clients for backend and external services
- src/hooks – custom React hooks encapsulating business logic & data fetching
- src/store – global state stores (auth, toast)
- src/utils, src/constants, src/types – shared utilities, constants, type definitions
- Deployment: Docker Compose for local dev; Vercel for production hosting.

##### Key insights from the README
- Application runs inside a Docker container via docker-compose up --build
- The frontend endpoint is served at localhost:5173
- Environment variables configure the API base URL
- No explicit backend code here—the app relies on remote services

## Diagram (Mermaid)

```mermaid
graph TB
    %% User & Browser Layer
    subgraph "User & Browser Layer"
        direction TB
        User["User"]:::external
        Browser["Browser"]:::external
        User -->|interacts via| Browser
    end

    %% CDN / Hosting Layer
    subgraph "CDN / Hosting Layer"
        direction TB
        CDN["CDN / Vercel"]:::infra
        Browser -->|fetches assets| CDN
    end

    %% SPA Application Layer
    subgraph "SPA Application Layer"
        direction TB

        %% Entry Point
        Entry["main.tsx / App.tsx"]:::infra
        click Entry "https://github.com/ozblind/ozblind_fe/blob/develop/src/main.tsx"
        click Entry "https://github.com/ozblind/ozblind_fe/blob/develop/src/App.tsx"

        %% Presentation Layer
        subgraph "Presentation Layer" 
            direction TB
            Pages["Pages (src/pages)"]:::ui
            Components["Components (src/components)"]:::ui
            Assets["Static Assets (src/assets)"]:::ui
            click Pages "https://github.com/ozblind/ozblind_fe/tree/develop/src/pages"
            click Components "https://github.com/ozblind/ozblind_fe/tree/develop/src/components"
            click Assets "https://github.com/ozblind/ozblind_fe/tree/develop/src/assets"
        end

        %% Routing Layer
        subgraph "Routing Layer"
            direction TB
            AppRouter["AppRouter (AppRouter.tsx)"]:::ui
            Guards["Route Guards (guards.tsx)"]:::ui
            click AppRouter "https://github.com/ozblind/ozblind_fe/blob/develop/src/router/AppRouter.tsx"
            click Guards "https://github.com/ozblind/ozblind_fe/blob/develop/src/router/guards.tsx"
        end

        %% Layout Layer
        subgraph "Layout Layer"
            direction TB
            RootLayout["RootLayout (RootLayout.tsx)"]:::ui
            MainLayout["MainLayout (MainLayout.tsx)"]:::ui
            click RootLayout "https://github.com/ozblind/ozblind_fe/blob/develop/src/layouts/RootLayout.tsx"
            click MainLayout "https://github.com/ozblind/ozblind_fe/blob/develop/src/layouts/MainLayout.tsx"
        end

        %% State Layer
        subgraph "State Layer"
            direction TB
            AuthStore["authStore (authStore.ts)"]:::data
            ToastStore["toastStore (toastStore.ts)"]:::data
            click AuthStore "https://github.com/ozblind/ozblind_fe/blob/develop/src/store/authStore.ts"
            click ToastStore "https://github.com/ozblind/ozblind_fe/blob/develop/src/store/toastStore.ts"
        end

        %% Business Logic Layer
        subgraph "Business Logic / Hooks"
            direction TB
            Hooks["Custom Hooks (src/hooks)"]:::logic
            Features["Feature Adapters (src/features)"]:::logic
            click Hooks "https://github.com/ozblind/ozblind_fe/tree/develop/src/hooks"
            click Features "https://github.com/ozblind/ozblind_fe/tree/develop/src/features"
        end

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            HTTP["HTTP Client Core (http.ts)"]:::data
            AuthAPI["Auth API (auth.ts)"]:::data
            PostsAPI["Posts API (posts.ts)"]:::data
            CommentsAPI["Comments API (comments.ts)"]:::data
            NotificationsAPI["Notifications API (notifications.ts)"]:::data
            BookmarksAPI["Bookmarks API (bookmarks.ts)"]:::data
            GitHubAPI["GitHub API (github.ts)"]:::data
            JobsAPI["Jobs APIs (jobs/index.ts)"]:::data

            click HTTP "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/http.ts"
            click AuthAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/auth.ts"
            click PostsAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/posts.ts"
            click CommentsAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/comments.ts"
            click NotificationsAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/notifications.ts"
            click BookmarksAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/bookmarks.ts"
            click GitHubAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/github.ts"
            click JobsAPI "https://github.com/ozblind/ozblind_fe/blob/develop/src/api/jobs/index.ts"
        end

        %% Shared Modules
        subgraph "Shared Modules"
            direction TB
            Constants["Constants (src/constants)"]:::infra
            Utils["Utilities (src/utils)"]:::infra
            Types["Types (src/types)"]:::infra
            click Constants "https://github.com/ozblind/ozblind_fe/tree/develop/src/constants"
            click Utils "https://github.com/ozblind/ozblind_fe/tree/develop/src/utils"
            click Types "https://github.com/ozblind/ozblind_fe/tree/develop/src/types"
        end

        %% Configuration & Deployment
        subgraph "Config & Deployment"
            direction TB
            ViteConfig["vite.config.ts"]:::infra
            EnvConfig["env.ts"]:::infra
            DockerCompose["docker-compose.yml"]:::infra
            VercelConfig["vercel.json"]:::infra
            click ViteConfig "https://github.com/ozblind/ozblind_fe/blob/develop/vite.config.ts"
            click EnvConfig "https://github.com/ozblind/ozblind_fe/blob/develop/src/config/env.ts"
            click DockerCompose "https://github.com/ozblind/ozblind_fe/blob/develop/docker-compose.yml"
            click VercelConfig "https://github.com/ozblind/ozblind_fe/blob/develop/vercel.json"
        end

        %% Internal flows
        CDN --> Entry
        Entry --> Pages
        Entry --> Components
        Pages --> AppRouter
        Components --> Hooks
        AppRouter --> Guards
        AppRouter --> RootLayout
        RootLayout --> MainLayout
        MainLayout --> Pages
        Components -->|uses| Hooks
        Hooks --> HTTP
        HTTP --> AuthAPI
        HTTP --> PostsAPI
        HTTP --> CommentsAPI
        HTTP --> NotificationsAPI
        HTTP --> BookmarksAPI
        HTTP --> GitHubAPI
        HTTP --> JobsAPI
        AuthAPI -->|writes/reads| AuthStore
        Components -->|subscribes| AuthStore
        Components -->|subscribes| ToastStore
        Hooks -->|dispatches| ToastStore
        Constants --> Pages
        Constants --> Components
        Utils --> Hooks
        Types --> Hooks

    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        BackendAPI["Backend REST API"]:::external
        ThirdPartyGitHub["GitHub API"]:::external
        ThirdPartyJobs["Job APIs"]:::external
        HTTP -->|HTTP calls| BackendAPI
        HTTP -->|HTTP calls| ThirdPartyGitHub
        HTTP -->|HTTP calls| ThirdPartyJobs
    end

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#0288D1
    classDef logic fill:#E8F5E9,stroke:#43A047
    classDef data fill:#FFF3E0,stroke:#FB8C00
    classDef external fill:#ECEFF1,stroke:#90A4AE,stroke-dasharray: 2 2
    classDef infra fill:#F3E5F5,stroke:#8E24AA
```
