# alunjax/halo architecture

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

- Interactive diagram: https://gitdiagram.com/alunjax/halo
- Repository: https://github.com/alunjax/halo

## Overview

##### Project Type and Purpose
- This is “Halo,” an open-source, full-stack, monolithic blog publishing application written in Java (Spring Boot).
- It serves both as backend (REST APIs, page rendering) and embeds a frontend admin UI (Freemarker templates & static resources).

##### Top-Level Architectural Layers
- Presentation Layer
- HTTP interface (controllers under `app/controller`) handling both admin UI and public content.
- Freemarker template engine (views under `src/main/resources/templates`).
- Business Layer
- Service classes (`app/service` + `app/service/impl`) implementing application logic.
- Caching and AOP aspects (`app/cache`, `app/aspect`) to optimize performance and apply cross-cutting concerns.
- Event-driven modules (`app/event`, `app/listener`) for decoupled actions (e.g., on comment, theme update).
- Data Access Layer
- Repositories (`app/repository`) using Spring Data JPA to talk to a relational database.
- Database migration scripts (`src/main/resources/migration`).
- Infrastructure & Integration
- File storage handlers (`app/handler/file`) for local or cloud object stores (AliOSS, Qiniu, etc.).
- Mail subsystem (`app/mail`) connecting to SMTP for notifications.
- Git-based theme fetcher/updater (`app/theme`) integrating with remote Git repos.
- Security filters & token services (`app/security`) managing authentication/authorization.
- Scheduled tasks (`app/task`) for maintenance (e.g., post cleanup).

##### External Dependencies & Services
- Relational Database (MySQL/Postgres/etc.)
- Cache store (in-memory or external, e.g. Caffeine/Redis)
- SMTP mail server
- Object storage (local FS or cloud OSS)
- Git repository host (for themes)
- Docker (deployment container)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser["Browser Client"]:::external
    CLI["CLI / Docker"]:::external

    %% Spring Boot Application as central node
    SpringApp["Spring Boot Application"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        Controllers["Controllers (REST & Page)"]:::presentation
        Templates["Freemarker Templates"]:::presentation
        Static["Admin UI Static Resources"]:::presentation
    end

    %% Business Layer
    subgraph "Business Layer"
        Services["Business Services"]:::business
        CacheModule["Caching Module"]:::business
        AOP["AOP Aspects"]:::business
        EventDefs["Event Definitions"]:::business
        EventBus["Event Bus"]:::business
        Listeners["Event Listeners"]:::business
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        Repos["JPA Repositories"]:::data
        Migrations["DB Migration Scripts"]:::data
    end

    %% Infrastructure & Integration
    subgraph "Infrastructure & Integration"
        FileHandlers["File Storage Handlers"]:::infra
        MailService["Mail Subsystem"]:::infra
        ThemeFetcher["Theme Fetcher/Updater"]:::infra
        Security["Security Filters & Token Service"]:::infra
        Tasks["Scheduled Tasks"]:::infra
    end

    %% External Systems
    DB[(Relational Database)]:::external
    CacheStore[(Cache Store)]:::external
    SMTP[(SMTP Server)]:::external
    OSS[(Object Storage)]:::external
    GitRepo[(Git Repository)]:::external

    %% Connections
    Browser -->|HTTP| SpringApp
    CLI -->|Launch| SpringApp

    SpringApp --> Controllers
    SpringApp --> Templates
    SpringApp --> Static

    Controllers -->|invoke| Services
    Services -->|JDBC| Repos
    Repos -->|JDBC| DB
    Services -->|get/set| CacheStore
    CacheModule -->|wraps| Services
    AOP -->|applies| Services

    Services -->|publish| EventBus
    EventBus -->|dispatch| Listeners
    Listeners -->|invoke| Services

    Services -->|S3 API| FileHandlers
    FileHandlers -->|S3 API| OSS

    Services -->|SMTP| MailService
    MailService -->|SMTP| SMTP

    Services -->|Git| ThemeFetcher
    ThemeFetcher -->|Git| GitRepo

    Tasks -->|schedule| Services
    Tasks -->|JDBC| Repos

    %% Click Events
    click Controllers "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/controller"
    click Templates "https://github.com/alunjax/halo/tree/master/src/main/resources/templates"
    click Static "https://github.com/alunjax/halo/tree/master/src/main/resources/admin"
    click Services "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/service"
    click CacheModule "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/cache"
    click AOP "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/aspect"
    click EventDefs "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/event"
    click Listeners "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/listener"
    click Repos "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/repository"
    click Migrations "https://github.com/alunjax/halo/tree/master/src/main/resources/migration"
    click FileHandlers "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/handler/file"
    click MailService "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/mail"
    click ThemeFetcher "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/theme"
    click Security "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/security"
    click Tasks "https://github.com/alunjax/halo/tree/master/src/main/java/run/halo/app/task"

    %% Styles
    classDef presentation fill:#D0E6FA,stroke:#0366d6,stroke-width:2px
    classDef business fill:#DFF2BF,stroke:#4F8A10,stroke-width:2px
    classDef data fill:#FFE6CC,stroke:#D2691E,stroke-width:2px
    classDef infra fill:#E6D0FA,stroke:#7D3C98,stroke-width:2px
    classDef external fill:#F2F2F2,stroke:#555555,stroke-width:2px,stroke-dasharray: 5 5
```
