# Architecture

This page shows go-scheduler's component layers and cross-cutting principles in a single overview diagram.

## System Overview

```mermaid
graph TB
    App[Caller] --> Cron[cron scheduler]
    Cron --> Parser[Expression parser]
    Cron --> Heap[Task min-heap]
    Heap --> Loop[Event loop goroutine]
    Loop -->|no deps| Direct[Direct goroutine run]
    Loop -->|has deps| Queue[Wait queue]
    Queue --> Workers[Dependency worker pool]
    Workers --> Manager[dependManager]
    Direct --> State[Task state]
    Manager --> State
```

## Layers

| Layer | Component | Files | Responsibility |
|---|---|---|---|
| Public interface | `cron` | `core/instance.go`, `core/add.go`, `core/remove.go`, `core/task.go` | `New` / `Start` / `Stop` / `Add` / `Remove` / `RemoveAll` / `List` |
| Parsing | `parser` | `core/schedule.go` | Turns a spec into `scheduleResult` (cron, descriptors) or `delayScheduleResult` (`@every`) |
| Scheduling | `taskHeap` | `core/task.go` | Min-heap ordered by `next`; the event loop only waits on the top entry |
| Execution | `cron.runAfter` | `core/instance.go` | Tasks without dependencies: goroutine run, timeout, panic recovery |
| Dependencies | `depend`, `dependManager` | `core/depend.go`, `core/dependManager.go` | Queue (capacity 1024), worker pool, prerequisite polling, result updates |

## Cross-Cutting Principles

| Principle | Implementation |
|---|---|
| One event loop owns the heap | After `Start`, add, remove, and clear go through the `add` / `remove` / `removeAll` channels; before `Start` the heap is modified directly |
| Per-task locking | Each `task` holds a `sync.RWMutex`; dependency checks read prerequisite `state` under a read lock |
| Dependent and plain tasks are split | `cron.run` runs directly or enqueues to the worker pool based on whether `after` is empty |
| Bounded worker count | `runtime.NumCPU()` when greater than 2, otherwise 2 |
| Shutdown does not interrupt actions | `Stop` waits for the WaitGroup and workers; actions do not receive a context |

## Further Reading

- [Task Model](/core-concepts) — task states
- [Task Dependencies](/core-concepts-dependencies) — dependency evaluation rules
- [Full architecture document](https://github.com/pardnchiu/go-scheduler/blob/main/doc/architecture.md) — per-module diagrams, data flow, and state machine