How astralapp/astral works
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