Quickstart Guide

This guide helps new developers and AI agents understand the Atlas codebase quickly.

First 5 Minutes

1. Understand what Atlas is

Atlas is a local-first data pipeline and reporting system that:

Loads source data from xlsx files into DuckDB (analytical) and LibSQL (operational)
Transforms raw data through dbt SQL models into analysis-ready mart tables
Assembles a structured report JSON from the mart data
Renders the report as editable PPTX slides, PDF, and a live web dashboard
Supports any reporting cadence: daily, weekly, monthly

2. Read these files in order

Order	File	Why
1	`@plan/concept.md`	What Atlas is, the problem it solves, and why it's built this way
2	`@plan/glossary.md`	Indonesian → English term mappings used throughout the codebase
3	`@plan/registry.md`	The actual entity, unit, and channel values used in data
4	`@plan/architecture.md`	Pipeline design, tech stack, and deployment phases
5	`@plan/analytics.md`	DuckDB layer definitions and mart SQL specs
6	`@plan/model.md`	LibSQL operational schema (38 tables)
7	`NETWORK.yml`	Ports and domains for all services
8	`AGENTS.md`	Commands, commit conventions, and workspace rules

3. Understand the directory structure

ions/
├── @plan/              # Planning docs, architecture, glossary, active plans
├── @repo/              # Shared infra: typescript presets, ESLint config, AI sync
├── @packages/          # Business-logic packages
│   ├── sync/           # Extract + Load — reads xlsx, populates DuckDB raw layer
│   ├── transform/      # dbt project — staging, intermediate, mart SQL models
│   ├── format/         # Format layer — reads marts, assembles report.json
│   └── db/             # Drizzle ORM schema for LibSQL operational layer
├── @services/          # Deployable applications
│   ├── plan/           # Fumadocs docs site serving @plan/ (plan.atlas.prata.ma)
│   ├── present/        # PPTX + PDF generator — reads report.json, produces slides
│   └── dashboard/      # TanStack Start web dashboard — live mart + record views
├── source/             # Raw xlsx source files (gitignored data)
│   └── config/         # Per-year YAML source configs (ions-2026.yaml, etc.)
├── output/             # Generated reports (gitignored)
│   ├── monthly/        # report.json, .pptx, .pdf per month
│   └── weekly/         # Weekly report outputs
├── atlas.db            # DuckDB analytical database (gitignored)
├── atlas-ops.db        # LibSQL operational database (gitignored)
├── NETWORK.yml         # Port and domain configuration (source of truth)
└── AGENTS.md           # AI agent instructions and workspace rules

Prerequisites

Tool	Purpose	Check
Bun	Runtime, package manager, monorepo	`bun --version`
uv	Python package manager for dbt	`uv --version`
DuckDB CLI	Inspect atlas.db directly	`duckdb --version`
LibreOffice	PDF conversion from PPTX	`libreoffice --version`

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install workspace dependencies
bun install

# Set up dbt Python environment
cd @packages/transform && uv venv && uv pip install -r requirements.txt

Running the Full Pipeline

Monthly report (e.g. February 2026)

# 1. Seed LibSQL lookup tables (first time only)
bun run sync:seed --entity IONS

# 2. Load xlsx into DuckDB raw layer
bun run sync --source xlsx --entity IONS --year 2026

# 3. Run dbt transforms
cd @packages/transform && uv run dbt run

# 4. Generate report.json
bun run format --entity IONS --period 2026-02

# 5. Generate PPTX + PDF
bun run present --entity IONS --period 2026-02

Output: output/monthly/2026-02-report.json, output/monthly/2026-02.pptx, output/monthly/2026-02.pdf

Single-month incremental sync

# Load only February data (faster than full-year sync)
bun run sync --source xlsx --entity IONS --year 2026 --month 2

Weekly report

bun run format --entity IONS --period 2026-02 --scope weekly
bun run present --entity IONS --period 2026-02 --scope weekly

Start the dashboard

bun run dev --filter @services/dashboard
# → http://localhost:15002

Start the plan docs site

bun run dev --filter @services/plan
# → http://localhost:15001

Service Ports (from NETWORK.yml)

Service	Port	Local domain
plan	15001	plan.atlas.test
dashboard	15002	dashboard.atlas.test

Common Tasks

Add a new year's data

Add source/config/ions-{year}.yaml with file paths, sheet names, column mappings, and header row offsets for the new year
Place the xlsx files in source/
Run bun run sync --source xlsx --entity IONS --year {year}
Run cd @packages/transform && uv run dbt run

The new year's data is now available in all mart queries and dashboard views.

Inspect raw data after sync

duckdb atlas.db -c "SHOW TABLES;"
duckdb atlas.db -c "SELECT COUNT(*) FROM raw_transactions;"
duckdb atlas.db -c "SELECT * FROM mart_revenue LIMIT 10;"

Verify dbt models

cd @packages/transform
uv run dbt run
uv run dbt test
uv run dbt docs generate && uv run dbt docs serve

Regenerate migrations after schema change

cd @packages/db
bunx drizzle-kit generate
bunx drizzle-kit push

Understanding the @plan/ Structure

Architecture vs. Plans

architecture.md is normative — the source of truth for how the system is designed
Plans in @plan/plans/ are execution artifacts — they implement architecture decisions
If a plan conflicts with architecture, review architecture first

Active Plans (`@plan/plans/`)

001 - 2026-02-20 - Plan Service/         # @services/plan — done
002 - 2026-02-20 - Sync and Source Config/
003 - 2026-02-20 - Transform Layer/
004 - 2026-02-20 - Format Layer/
005 - 2026-02-20 - Operational Database/
006 - 2026-02-20 - Present Service/
007 - 2026-02-20 - Dashboard Service/

Each plan folder contains five files:

plan/
├── Plan.md       # Goals, phases, success criteria, boundaries
├── Tasks.md      # Task breakdown with T-XXX IDs and acceptance criteria
├── Progress.md   # Append-only execution log
├── Review.md     # Append-only compliance review log
└── Summary.md    # Current state for AI session handoff

Plan status meanings:

draft — Defined, not yet started
active — Currently being executed
paused — Work temporarily stopped
completed — All tasks done, success criteria met

Getting Help

What is Atlas? → @plan/concept.md
Architecture decisions → @plan/architecture.md
Term unclear? → @plan/glossary.md
Which unit code is which? → @plan/registry.md
How are marts defined? → @plan/analytics.md
What's the DB schema? → @plan/model.md
Which port does X run on? → NETWORK.yml
Build/lint/test commands → AGENTS.md

Quickstart Guide

On this page