# AstroChart — Source Code Reference

**Library**: AstroChart (a.k.a. AstroDraw)
**Description**: A free and open-source JavaScript/TypeScript library for generating SVG charts to display planets in astrology.
**Doc site**: https://astrodraw.github.io/
**GitHub repo**: https://github.com/AstroDraw/AstroChart
**Branch**: `main`

---

## Repository Structure

The source code lives under `project/` (not `src/`). Build output (the bundle consumed end-users) is in `dist/`.

```
AstroChart/
├── dist/
│   ├── astrochart.js              # Webpack-bundled build (99KB) — what the docs site loads
│   └── project/                   # Sub-bundle for project-mode imports
├── project/
│   ├── src/                       # TypeScript source
│   │   ├── index.ts               (172B)   — Public API entry, re-exports Chart
│   │   ├── chart.ts               (4KB)    — Chart class, public entry point
│   │   ├── svg.ts                 (84KB)   — SVG drawing primitives + all planet/zodiac glyphs
│   │   ├── radix.ts               (19KB)   — Radix chart composition (drawBg, drawUniverse, drawPoints...)
│   │   ├── transit.ts             (13KB)   — Transit chart overlay
│   │   ├── aspect.ts              (8KB)    — Aspect calculation engine
│   │   ├── zodiac.ts              (10KB)   — Zodiac logic, dignities, retrograde
│   │   ├── settings.ts            (8KB)    — Default config (colors, ratios, symbols, scale)
│   │   ├── utils.ts               (12KB)   — Geometry: getPointPosition, getRulerPositions, collision
│   │   ├── animation/
│   │   │   ├── animator.ts        (5KB)    — Animated chart transitions
│   │   │   └── timer.ts           (1KB)    — Animation timing helper
│   │   └── *.test.ts              — Jest test suite
│   ├── examples/                  — Usage examples
│   └── __tests__/                 — Additional tests
├── website/                       # Docusaurus doc site source (what renders astrodraw.github.io)
├── docs/                          # Doc site content (markdown)
├── doc/                           # Older documentation
├── package.json
├── tsconfig.json
├── webpack.config.js
└── jest.config.js
```

---

## Chart Rendering Flow

### Public API

```typescript
// project/src/chart.ts
class Chart {
  constructor(elementId: string, width: number, height: number, settings?: Partial<Settings>)
  radix(data: AstroData): Radix      // Draw a natal/radix chart
  transit(data: AstroData): Transit  // Draw a transit overlay
  scale(factor: number): void        // Scale the chart
  calibrate(): Chart                 // Debug overlay
}
```

```typescript
// project/src/index.ts — re-exports Chart as default
```

### Drawing Pipeline (inside `Radix`)

Order of operations in `Radix` constructor + draw methods:

| Step | Method | File | What it does |
|------|--------|------|--------------|
| 1 | `drawBg()` | `project/src/radix.ts` | Background hemisphere via `paper.segment()` |
| 2 | `drawUniverse()` | `project/src/radix.ts` | 12 zodiac sign color segments + 12 zodiac symbol glyphs |
| 3 | `drawRuler()` | `project/src/radix.ts` | Degree tick marks around the wheel |
| 4 | `drawPoints()` | `project/src/radix.ts` | Planet symbols, pointer lines, degree/retro/dignity labels |
| 5 | `drawCusps()` | `project/src/radix.ts` | 12 cusp lines (dashed around planets), house numbers |
| 6 | `drawAxis()` | `project/src/radix.ts` | Asc/Ds/Ic/Mc axis lines with symbols |
| 7 | `drawCircles()` | `project/src/radix.ts` | Outer, inner, indoor circle strokes |

Aspects are drawn via `Radix.aspects()` which uses `project/src/aspect.ts`.

---

## Key Source Files (download URLs)

### Core rendering

| File | Description |
|------|-------------|
| [svg.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/svg.ts) | SVG primitives: `segment()`, `circle()`, `line()`, `text()`, and 50+ glyph methods (`sun()`, `moon()`, `aries()`, `taurus()`, ... `pluto()`, `chiron()`, `nnode()`, `fortune()`). The `<path d="...">` arc math lives at lines ~1468-1478. |
| [radix.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/radix.ts) | Chart composition — orchestrates all SVG calls. `LocatedPoint` interface, `AstroData` type, collision avoidance via `assemble()`. |
| [chart.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/chart.ts) | Public entry point. Creates `SVG`, delegates to `Radix` or `Transit`. |

### Data + logic

| File | Description |
|------|-------------|
| [settings.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/settings.ts) | Default constants: `COLORS_SIGNS`, `SYMBOL_SIGNS`, `INNER_CIRCLE_RADIUS_RATIO`, `INDOOR_CIRCLE_RADIUS_RATIO`, `RULER_RADIUS`, `SYMBOL_SCALE`, `PADDING`, etc. |
| [utils.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/utils.ts) | `getPointPosition()`, `getRulerPositions()`, `getDashedLinesPositions()`, `getDescriptionPosition()`, `assemble()`, `validate()`, `radiansToDegree()`. |
| [zodiac.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/zodiac.ts) | Zodiac sign boundaries, essential dignities (domicile, exaltation, detriment, fall), retrograde detection. |
| [aspect.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/aspect.ts) | `AspectCalculator` class — computes aspects between planet points (conjunction, opposition, trine, square, sextile, etc.). |
| [transit.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/transit.ts) | Transit chart — draws on top of an existing radix. |
| [animation/animator.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/animation/animator.ts) | Animated chart transitions. |
| [animation/timer.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/animation/timer.ts) | Animation timing helper. |
| [index.ts](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/project/src/index.ts) | Public API barrel file. |

### Built artifact

| File | Description |
|------|-------------|
| [dist/astrochart.js](https://raw.githubusercontent.com/AstroDraw/AstroChart/main/dist/astrochart.js) | Webpack bundle — the file loaded by the doc site and distributed to end-users. |

---

## SVG Primitives API (svg.ts)

| Method | Signature | Purpose |
|--------|-----------|---------|
| `segment()` | `(x, y, radius, a1, a2, thickness, lFlag?, sFlag?)` | Arc slice (used for sign segments, background) |
| `circle()` | `(cx, cy, radius)` | Circle stroke (chart rings) |
| `line()` | `(x1, y1, x2, y2)` | Straight line (cusps, pointers, ruler ticks) |
| `text()` | `(txt, x, y, size, color)` | Symbol/text glyph |
| `getSymbol()` | `(name, x, y)` | Dispatches to the correct glyph method |
| `radialLine()` | — | Radial spoke from center to edge |

**Key constants** (defined in `settings.ts`, used in `svg.ts` line ~1468):
- `LARGE_ARC_FLAG = 1`
- `SWEET_FLAG = 0`

---

## Doc Site (what renders the GitHub Pages UI)

The documentation site that appears at https://astrodraw.github.io/ is built with **Docusaurus v2.3.1** (seen in `<meta name="generator">`).

| File | Description |
|------|-------------|
| [website/](https://github.com/AstroDraw/AstroChart/tree/main/website) | Docusaurus source (docusaurus.config, sidebar, pages) |
| [docs/](https://github.com/AstroDraw/AstroChart/tree/main/docs) | Doc content markdown |

The homepage hero banner contains an inline SVG showing a React-like logo (unrelated to this library — it's Docusaurus template branding). The actual AstroChart demo rendering on the page uses the `Chart` class targeting `<div id="paper">`.

---

## Key Data Structures

```typescript
// From radix.ts
export type Points = Record<string, number[]>
export interface LocatedPoint {
  name: string   // planet name, e.g. "Sun", "Moon"
  x: number      // computed screen x
  y: number      // computed screen y
  r: number      // collision radius
  angle: number  // shifted position in degrees
  pointer?: number
  index?: number
}
export interface AstroData {
  planets: Points   // {"Sun":[120], "Moon":[45], ...}
  cusps: number[]   // [300, 340, 30, 60, 75, 90, 116, 172, 210, 236, 250, 274]
}
```

---

## Notes

- The library is **TypeScript** (compiled via webpack, not tsc).
- No runtime dependencies — pure DOM SVG manipulation.
- Tests use **Jest** (`jest.config.js`).
- The `project/` subdirectory is the actual library source; the repo root contains build/config/docs.