· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·

Architecture Overview

Astral Architecture
Architecture / Overview

System Design

This document provides a high-level overview of Astral's architecture. Understanding these layers will help you contribute to the project or integrate Astral into your tooling.

Architectural Layers

Astral is organized into well-defined layers, each with specific responsibilities:

Layer Diagram
CLI Layer
Command parsing, user interaction, output formatting
Command Layer
High-level operations: save, merge, stack navigation
Core Layer
Repository, refs, working tree, index operations
Object Store
Content-addressable storage, Blake3 hashing
Filesystem
I/O operations, .asl directory structure

Layer Details

CLI Layer

The CLI layer handles user interaction:

  • Argument parsing: Flag processing, subcommand routing
  • Configuration loading: Reading from config files and environment
  • Output formatting: Pretty printing, JSON output, terminal colors
  • Error presentation: User-friendly error messages
// cmd/asl/main.go
func main() {
    cli.Run(os.Args)
}

Command Layer

High-level commands that compose core operations:

  • Save: Snapshot working tree changes to a new commit
  • Merge: Three-way merge with conflict handling
  • Stack: Navigate and manipulate commit stacks
  • Branch: Create, delete, and switch branches

Core Layer

The heart of Astral's functionality:

  • Repository: Overall repository state and operations
  • Refs: Branch and tag management
  • Working Tree: File status, diff computation
  • Commit Graph: History traversal and analysis

Object Store

The content-addressable storage layer:

  • Blobs: Raw file content storage
  • Trees: Directory structure representation
  • Commits: Snapshot metadata

Directory Structure

The .asl directory contains all repository data:

.asl/

├──objects/Content-addressable storage
│├──8f/Objects by first 2 hash chars
│└──pack/Packed objects for efficiency
├──refs/Branch and tag pointers
│├──heads/Branch references
│└──tags/Tag references
├──HEADCurrent branch reference
└──configRepository configuration

Key Design Decisions

Lock-Free Operations

Astral uses optimistic concurrency. Most operations can proceed without locks, with conflict detection at write time.

Parallel by Default

Status checks, diff computation, and object hashing leverage all available CPU cores.

Minimal Dependencies

Astral has no runtime dependencies. A single static binary works everywhere.

Testable Architecture

Clear layer boundaries enable unit testing at each level with minimal mocking.

Next Steps

Deep Dive
Blake3 Hashing →
Concept
Object Store →
└─── End of Document ───┘