# astralapp/astral architecture

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

- Interactive diagram: https://gitdiagram.com/astralapp/astral
- Repository: https://github.com/astralapp/astral

## Overview

##### Project Type and Purpose
– Astral is a full-stack, monolithic web application built on Laravel (PHP) for the backend and Vue.js for the frontend. Its purpose is to let users self-host or use a hosted service to organize their GitHub Stars via an OAuth integration with the GitHub API.

##### Main Architectural Components
a. Frontend (Vue.js SPA)
- Location: resources/assets/js (components, router, store, utils)
- Build tool: Webpack (webpack.mix.js), Yarn
- Responsibilities:
– Authentication UI (Auth/Index.vue)
– Dashboard (stars listing, notes editor, tag management)
– State management (Vuex store modules under store/modules)
– API client to Laravel backend (store/api/client.js)
b. Backend (Laravel MVC API + Web)
- Location: app/Http/Controllers, app/Models, app/Lib, routes/
- Responsibilities:
– HTTP Layer:
- Routes: web.php (serves index.blade.php) and api.php (JSON API)
- Controllers: AuthController, StarsController, TagsController, etc.
– Business Logic: Services in app/Lib (Autotagger, GitHubClient, StarsJanitor)
– Data Layer: Eloquent models (Star, Tag, Predicate, User) + Scopes
– Console Layer: Artisan commands (install, clear tokens) and scheduled janitor
c. Database (Relational)
- Defined by migrations under database/migrations
- Tables: users, stars, tags, star_tag pivot, predicates, etc.
d. External Services
- GitHub OAuth & GraphQL/REST API (app/Lib/GitHubClient.php)
e. Cache / Session / Queue
- Configurable in config/cache.php, config/session.php, config/queue.php
- Could be Redis, database, or file‐based drivers
- Jobs triggered by console/kernel or controllers for background tasks
f. Storage & Assets
- Public folder serves compiled CSS/JS and images
- Blade entrypoint (public/index.php → resources/views/index.blade.php)

##### Component Interactions and Data Flow
Browser (Vue SPA)
↓ HTTP(S)
Web Server (Nginx/Apache)
→ public/index.php
→ Laravel Middleware → AuthController or API Controllers
Laravel Service Layer
→ Eloquent Models ↔ Database
→ GitHubClient ↔ GitHub API
Background Jobs (Scheduler / Queue Worker)
→ StarsJanitor, ClearAccessTokensCommand

##### Architectural Patterns & Principles
– MVC in Laravel (Controllers → Models → Views)
– Service Layer / Library classes for external API and domain logic (app/Lib)
– Vuex for frontend state management
– Single-Page Application served by a minimal Blade template
– Separation of concerns: Authentication, Data Fetching, UI Rendering, Business Rules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Browser (Vue.js SPA)" 
        direction TB
        AuthUI["Auth UI\n(Auth/Index.vue)"]:::frontend
        Dashboard["Dashboard Components\n(resources/assets/js/components/Dashboard)"]:::frontend
        Router["Router\n(resources/assets/js/router/index.js)"]:::frontend
        Store["Vuex Store\n(resources/assets/js/store/modules)"]:::frontend
        APIClient["API Client\n(resources/assets/js/store/api/client.js)"]:::frontend
        Utils["Utilities\n(resources/assets/js/utils\nresources/assets/js/filters)"]:::frontend
    end

    subgraph "App Server (Laravel)" 
        direction TB
        subgraph "HTTP Layer"
            direction TB
            WebRoutes["Web Routes\n(routes/web.php)"]:::backend
            APIRoutes["API Routes\n(routes/api.php)"]:::backend
            Middleware["OAuth Middleware\n(app/Http/Middleware/RefreshToken.php)"]:::backend
            Controllers["Controllers"]:::backend
        end
        subgraph "Controllers"
            direction TB
            AuthCtrl["AuthController"] 
            StarsCtrl["StarsController"] 
            TagsCtrl["TagsController"] 
            GitHubStarsCtrl["GitHubStarsController"] 
            PredicatesCtrl["PredicatesController"] 
            StarNotesCtrl["StarNotesController"] 
            StarTagsCtrl["StarTagsController"] 
            JanitorCtrl["StarsJanitorController"] 
        end
        subgraph "Service Layer"
            direction TB
            Autotagger["Autotagger"] 
            GitHubClient["GitHubClient"] 
            StarsJanitor["StarsJanitor"] 
        end
        subgraph "Data Layer"
            direction TB
            StarModel["Star"] 
            TagModel["Tag"] 
            PredicateModel["Predicate"] 
            UserModel["User"] 
        end
        subgraph "Console"
            direction TB
            InstallCmd["InstallCommand"] 
            ClearTokensCmd["ClearAccessTokensCommand"] 
            Kernel["Console Kernel"] 
        end
        Blade["SPA Entrypoint\n(resources/views/index.blade.php)"]:::backend
        PublicIndex["Public PHP Entry\n(public/index.php)"]:::backend
    end

    subgraph "Infrastructure & Data"
        direction TB
        Database["Database"]:::database
        Migrations["Migrations\n(database/migrations)"]:::database
        Factories["Factories\n(database/factories)"]:::database
        CacheStack["Cache/Session/Queue\n(config/cache.php\nconfig/session.php\nconfig/queue.php)"]:::cache
        PublicAssets["Public Assets\n(public/css & public/js)"]:::assets
        Webpack["Webpack Build Tool\n(webpack.mix.js)"]:::assets
        Artisan["Artisan CLI"]:::backend
        GitHubCloud["GitHub API/OAuth"]:::external
    end

    %% Connections
    User["User"]:::actor --> AuthUI
    User --> Dashboard

    AuthUI --> Router
    Dashboard --> Router
    Router --> Store
    Store --> APIClient
    APIClient --> APIRoutes
    APIRoutes --> Controllers
    WebRoutes --> Blade
    Blade --> PublicIndex

    Controllers --> Autotagger
    Controllers --> GitHubClient
    Controllers --> StarsJanitor
    Controllers --> StarModel
    Controllers --> TagModel
    Controllers --> PredicateModel
    Controllers --> UserModel

    GitHubClient --> GitHubCloud
    Controllers --> CacheStack
    Controllers --> Database
    Database --> StarModel
    Database --> TagModel
    Database --> PredicateModel
    Database --> UserModel

    Kernel --> StarsJanitor
    Kernel --> ClearTokensCmd
    Kernel --> InstallCmd

    Webpack --> PublicAssets
    Artisan --> Kernel

    %% Click Events
    click AuthUI "https://github.com/astralapp/astral/blob/main/resources/assets/js/components/Auth/Index.vue"
    click Dashboard "https://github.com/astralapp/astral/tree/main/resources/assets/js/components/Dashboard"
    click Router "https://github.com/astralapp/astral/blob/main/resources/assets/js/router/index.js"
    click Store "https://github.com/astralapp/astral/tree/main/resources/assets/js/store/modules"
    click APIClient "https://github.com/astralapp/astral/blob/main/resources/assets/js/store/api/client.js"
    click Utils "https://github.com/astralapp/astral/tree/main/resources/assets/js/utils"
    click WebRoutes "https://github.com/astralapp/astral/blob/main/routes/web.php"
    click APIRoutes "https://github.com/astralapp/astral/blob/main/routes/api.php"
    click AuthCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/AuthController.php"
    click StarsCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/StarsController.php"
    click TagsCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/TagsController.php"
    click GitHubStarsCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/GitHubStarsController.php"
    click PredicatesCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/PredicatesController.php"
    click StarNotesCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/StarNotesController.php"
    click StarTagsCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/StarTagsController.php"
    click JanitorCtrl "https://github.com/astralapp/astral/blob/main/app/Http/Controllers/StarsJanitorController.php"
    click Middleware "https://github.com/astralapp/astral/blob/main/app/Http/Middleware/RefreshToken.php"
    click StarModel "https://github.com/astralapp/astral/blob/main/app/Models/Star.php"
    click TagModel "https://github.com/astralapp/astral/blob/main/app/Models/Tag.php"
    click PredicateModel "https://github.com/astralapp/astral/blob/main/app/Models/Predicate.php"
    click UserModel "https://github.com/astralapp/astral/blob/main/app/Models/User.php"
    click Autotagger "https://github.com/astralapp/astral/blob/main/app/Lib/Autotagger.php"
    click GitHubClient "https://github.com/astralapp/astral/blob/main/app/Lib/GitHubClient.php"
    click StarsJanitor "https://github.com/astralapp/astral/blob/main/app/Lib/StarsJanitor.php"
    click ClearTokensCmd "https://github.com/astralapp/astral/blob/main/app/Console/Commands/ClearAccessTokensCommand.php"
    click InstallCmd "https://github.com/astralapp/astral/blob/main/app/Console/Commands/InstallCommand.php"
    click Kernel "https://github.com/astralapp/astral/blob/main/app/Console/Kernel.php"
    click Migrations "https://github.com/astralapp/astral/tree/main/database/migrations"
    click Factories "https://github.com/astralapp/astral/tree/main/database/factories"
    click CacheStack "https://github.com/astralapp/astral/blob/main/config/cache.php"
    click Webpack "https://github.com/astralapp/astral/blob/main/webpack.mix.js"
    click PublicAssets "https://github.com/astralapp/astral/tree/main/public/js"
    click Blade "https://github.com/astralapp/astral/blob/main/resources/views/index.blade.php"
    click PublicIndex "https://github.com/astralapp/astral/blob/main/public/index.php"
    click Artisan "https://github.com/astralapp/astral/tree/main/artisan"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E8F5E9,stroke:#34A853,color:#34A853
    classDef database fill:#FFF3E0,stroke:#FB8C00,color:#FB8C00
    classDef cache fill:#EDE7F6,stroke:#5E35B1,color:#5E35B1
    classDef assets fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA
    classDef external fill:#E1F5FE,stroke:#039BE5,color:#039BE5
    classDef actor fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2
```
