# connortran216/horizon-blog architecture

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

- Interactive diagram: https://gitdiagram.com/connortran216/horizon-blog
- Repository: https://github.com/connortran216/horizon-blog

## Overview

##### Project type and purpose
- This is a single-page, full-stack-ready **frontend application** (Personal Blog) built with React, TypeScript, Vite, and Chakra UI.
- It provides a responsive blog with authentication, rich-text editing (using Lexical), search/filter, and contact features.
- Although it’s currently using localStorage via a `blogStorage` service, it is designed to integrate with a backend (e.g., Django REST API).

##### File structure
- Top level:
- Dockerfile, docker-compose.yml — containerization
- index.html, public/ — static assets
- src/ — all application code
- src/ folders:
- core/ — shared business logic (services, types, utils, ErrorBoundary)
- components/ — feature-specific UI (layout, editor, reader)
- pages/ — route-level React views
- context/ — global state (AuthContext)
- config/ — editor and runtime config
- theme/ — Chakra UI theme
- Routes.tsx & App.tsx — React Router setup and root component
- main.tsx — entry point (renders App with providers)
- Config files: tsconfig.json, vite.config.ts, .env variants, package.json.

##### README for additional insights
- Mentions planned REST endpoints (`/api/auth/login`, `/api/posts`, etc.).
- Describes directory intentions under “Project Architecture.”

a. Main components:
1. Client (Browser)
2. Static server / CDN (serves index.html & JS bundle)
3. React SPA
- App shell + Router
- AuthContext provider
- Page components (Home, Blog, BlogDetail, BlogEditor, etc.)
- UI components (Navbar, Footer, Editor, Reader)
4. Core services
- AuthService → /api/auth
- ApiService → /api/posts, /api/contact
- StorageService → localStorage (fallback)
5. Lexical Editor subsystem
- MilkdownEditor, plugins, Markdown support
6. External services (future)
- REST API (Django backend)
- Auth (JWT)
b. Relationships & interactions:
- Browser requests index.html → Static server (Docker/Nginx).
- React SPA initializes in Browser, sets up AuthContext.
- User navigates via React Router to pages.
- Page components call core services:
- AuthService.login() → HTTP POST to `/api/auth/login`
- ApiService.getPosts() → HTTP GET `/api/posts`
- StorageService.read()/write() → localStorage fallback.
- BlogEditor uses Lexical editor components and plugins.
- Contact page posts to `/api/contact`.
c. Architectural patterns & principles:
- Component hierarchy: Pages → Feature components → Core UI components.
- Separation of concerns:
- UI layer (components/layout, pages)
- Business logic layer (core/services, core/utils)
- State management (context)
- Single source of truth for config (.env, vite.config, src/config).
- Fallback pattern: localStorage service until API is available.
d. Key technologies:
- React 18 + TS + Vite
- Chakra UI for styling
- React Router DOM for client-side routing
- Lexical editor with Markdown plugin
- Axios or fetch within ApiService (not shown but implied)
- Docker + docker-compose for containerization

##### Detailed capturing of essential elements
- Data flow on login, fetch posts, save post.
- Context provider and theme/provider wrappers.
- Environment configs (.env.development vs production).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser"]:::external
    StaticServer["Static Server / CDN"]:::external
    Browser -->|"GET index.html & JS bundle"| StaticServer
    StaticServer -->|"Serves files"| SPA["React SPA"]:::ui

    click SPA "https://github.com/connortran216/horizon-blog/blob/main/src/main.tsx"

    SPA -->|"Initialize"| AppShell["App Shell & Router"]:::ui
    click AppShell "https://github.com/connortran216/horizon-blog/blob/main/src/App.tsx"
    SPA -->|"Wrap with"| AuthContext["AuthContext Provider"]:::ui
    click AuthContext "https://github.com/connortran216/horizon-blog/blob/main/src/context/AuthContext.tsx"
    SPA -->|"Load theme"| Theme["Chakra UI Theme"]:::ui
    click Theme "https://github.com/connortran216/horizon-blog/blob/main/src/theme/index.ts"

    subgraph "Pages (UI Layer)" 
        direction TB
        HomePage["Home Page"]:::ui
        click HomePage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Home.tsx"
        BlogListPage["Blog List Page"]:::ui
        click BlogListPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Blog.tsx"
        BlogDetailPage["Blog Detail Page"]:::ui
        click BlogDetailPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/BlogDetail.tsx"
        BlogEditorPage["Blog Editor Page"]:::ui
        click BlogEditorPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/BlogEditor.tsx"
        ContactPage["Contact Page"]:::ui
        click ContactPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Contact.tsx"
        LoginPage["Login Page"]:::ui
        click LoginPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Login.tsx"
        RegisterPage["Register Page"]:::ui
        click RegisterPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Register.tsx"
        ProfilePage["Profile Page"]:::ui
        click ProfilePage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/Profile.tsx"
        ProfileBlogDetailPage["Profile Blog Detail Page"]:::ui
        click ProfileBlogDetailPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/ProfileBlogDetail.tsx"
        AboutPage["About Page"]:::ui
        click AboutPage "https://github.com/connortran216/horizon-blog/blob/main/src/pages/About.tsx"
    end

    AppShell --> HomePage
    AppShell --> BlogListPage
    AppShell --> BlogDetailPage
    AppShell --> BlogEditorPage
    AppShell --> ContactPage
    AppShell --> LoginPage
    AppShell --> RegisterPage
    AppShell --> ProfilePage
    AppShell --> ProfileBlogDetailPage
    AppShell --> AboutPage

    subgraph "Layout Components" 
        direction TB
        Navbar["Navbar"]:::ui
        click Navbar "https://github.com/connortran216/horizon-blog/blob/main/src/components/layout/Navbar.tsx"
        LayoutWrapper["Layout Wrapper"]:::ui
        click LayoutWrapper "https://github.com/connortran216/horizon-blog/blob/main/src/components/layout/Layout.tsx"
        Footer["Footer"]:::ui
        click Footer "https://github.com/connortran216/horizon-blog/blob/main/src/components/layout/Footer.tsx"
    end

    HomePage --> LayoutWrapper
    BlogListPage --> LayoutWrapper
    BlogDetailPage --> LayoutWrapper
    BlogEditorPage --> LayoutWrapper
    ContactPage --> LayoutWrapper
    LoginPage --> LayoutWrapper
    RegisterPage --> LayoutWrapper
    ProfilePage --> LayoutWrapper
    ProfileBlogDetailPage --> LayoutWrapper
    AboutPage --> LayoutWrapper

    LayoutWrapper --> Navbar
    LayoutWrapper --> Footer

    subgraph "Editor Subsystem" 
        direction TB
        MilkdownEditor["Milkdown Editor Component"]:::ui
        click MilkdownEditor "https://github.com/connortran216/horizon-blog/blob/main/src/components/editor/MilkdownEditor.tsx"
        HashtagPlugin["Hashtag Plugin"]:::ui
        click HashtagPlugin "https://github.com/connortran216/horizon-blog/blob/main/src/components/editor/plugins/hashtagPlugin.ts"
        WikiLinkPlugin["WikiLink Plugin"]:::ui
        click WikiLinkPlugin "https://github.com/connortran216/horizon-blog/blob/main/src/components/editor/plugins/wikiLinkPlugin.ts"
        MilkdownEditor --> HashtagPlugin
        MilkdownEditor --> WikiLinkPlugin
    end

    BlogEditorPage --> EditorSubsystem{" "}

    subgraph "Reader Component"
        MilkdownReader["Milkdown Reader"]:::ui
        click MilkdownReader "https://github.com/connortran216/horizon-blog/blob/main/src/components/reader/MilkdownReader.tsx"
    end

    BlogDetailPage --> MilkdownReader
    ProfileBlogDetailPage --> MilkdownReader

    subgraph "Core Services" 
        direction TB
        AuthService["AuthService"]:::service
        click AuthService "https://github.com/connortran216/horizon-blog/blob/main/src/core/services/auth.service.ts"
        ApiService["API Service"]:::service
        click ApiService "https://github.com/connortran216/horizon-blog/blob/main/src/core/services/api.service.ts"
        StorageService["Storage Service"]:::service
        click StorageService "https://github.com/connortran216/horizon-blog/blob/main/src/core/services/storage.service.ts"
    end

    HomePage -->|"fetch posts"| ApiService
    BlogListPage -->|"getPosts()"| ApiService
    BlogDetailPage -->|"getPost()"| ApiService
    BlogEditorPage -->|"savePost()"| ApiService
    ContactPage -->|"submitContact()"| ApiService
    LoginPage -->|"login()"| AuthService
    RegisterPage -->|"register()"| AuthService
    ProfilePage -->|"getProfile()"| ApiService
    ProfileBlogDetailPage -->|"getUserPost()"| ApiService

    AuthContext --> AuthService
    SPA --> ApiService
    SPA --> StorageService
    StorageService -->|"localStorage fallback"| LS["localStorage"]:::external

    ApiService -->|"HTTP calls"| ExternalAPI["Django REST API"]:::external
    AuthService -->|"HTTP calls"| ExternalAPI
    ContactPage -->|"POST /api/contact"| ExternalAPI

    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#E6FFFA,stroke:#02897A,color:#02897A;
    classDef external fill:#FFF5BA,stroke:#D4A017,color:#D4A017;
```
