# piiton345/calcore architecture

> Architecture diagram of the GitHub repository piiton345/calcore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piiton345/calcore
- Repository: https://github.com/piiton345/calcore

## Overview

1. **Project type and runtime**
   - `calcore` is a **Node.js package** implementing an **interpreter for a date-encoded esoteric language**.
   - The repository contains source in `src/`, a compiled distributable in `dist/`, and example `.clc` programs in `example/`.

2. **Primary entrypoint**
   - `src/calcore.js` is the central runtime/interpreter module.
   - The published CLI behavior described in the README (`calcore [option] [filepath]`) likely routes through this file, which reads a `.clc` program, interprets it, and handles post-run output behavior.

3. **Language model**
   - A program is a plain text file where each instruction is represented by a date-like token.
   - The **first line specifies the date format convention** for the file; subsequent lines use that same convention.
   - The interpreter must therefore normalize and decode dates before executing commands.

4. **Command dispatch by month**
   - The source is split into **month-specific modules**:
     - `src/January.js`
     - `src/February.js`
     - `src/March.js`
     - `src/April.js`
   - This strongly suggests a command-dispatch architecture where the interpreter parses the month/day portion of each token and forwards execution to the corresponding month handler.

5. **Execution state**
   - The language uses a **memory tape** with a movable pointer, so the interpreter maintains:
     - the tape itself,
     - the current pointer position,
     - output accumulation state,
     - and control-flow position for jumps.
   - Because commands can read/write by pointer and by index, the core runtime is stateful and sequential rather than expression-based.

6. **Instruction categories**
   - The README defines four functional groups that map cleanly to subsystem boundaries:
     - **January**: input, output buffering, unconditional and conditional jumps.
     - **February**: value assignment, pointer movement, copy operations, type conversion.
     - **March**: arithmetic.
     - **April**: output reset and current-time/system-date queries.
   - Architecturally, these are the primitive operations the interpreter exposes; all program behavior is composed from them.

7. **Control flow**
   - Jump commands are a major architectural feature.
   - The runtime interprets “execution position” as **line number order**, with the first program line counted as 1.
   - Conditional jumps compare values stored on the tape and redirect the interpreter to another line, so the execution engine must support non-linear line traversal.

8. **Parsing and normalization boundary**
   - The language accepts multiple date formats (`YYYY/MM/DD`, `MM-DD-YYYY`, `DD.MM.YYYY`, etc.).
   - A key boundary in the architecture is the **parser/lexer layer**, which must:
     - recognize the program-wide date convention from line 1,
     - tokenize command and argument dates,
     - distinguish command identity from numeric/character literal values encoded as dates.

9. **Type system boundary**
   - The language is intentionally minimal but still type-aware:
     - numeric values are day offsets from `2000/1/1`,
     - characters are Unicode code points,
     - variable cells can be empty, numeric, or character typed.
   - `February` commands handle conversions and type inspection, so the interpreter likely preserves type metadata per tape cell.

10. **I/O flow**
   - Input is line-based: `1/1` reads a line and stores characters one by one onto the tape.
   - Output is buffered via `1/2` and flushed by `1/3`.
   - The runtime therefore has an **output buffer separate from the tape**, and final program termination may also auto-flush leftover buffered output, per the README.

11. **System interaction**
   - `April.js` exposes system time/date primitives, making the interpreter partially dependent on the host environment.
   - That means program output can depend on runtime execution time, not just source content.

12. **Distribution layout**
   - `dist/calcore.js` is the built artifact shipped for consumption.
   - `package.json` likely wires the CLI package name and executable entrypoint to the built file, while `src/` remains the maintainable source-of-truth.

13. **Examples and documentation**
   - `example/Hello_world.clc` and `example/example1.clc` are integration-style sample programs.
   - `src/命令一覧.txt` appears to be a localized command reference, useful as a source-side spec companion to the README.

14. **Overall architectural shape**
   - This repo is best understood as:
     - a **date-token parser**,
     - a **stateful tape-based interpreter**,
     - a **month-based opcode library**,
     - and a **CLI/distribution wrapper**.
   - For an architecture diagram, the main data flow is: `.clc file` → parser/date normalization → opcode dispatch by month/day → tape/output/system-state mutation → final output/flush.

Main entry points: [`src/calcore.js`](https://github.com/piiton345/calcore/blob/main/src/calcore.js) (Interpreter), [`src/January.js`](https://github.com/piiton345/calcore/blob/main/src/January.js) (January), [`src/April.js`](https://github.com/piiton345/calcore/blob/main/src/April.js) (April), [`src/February.js`](https://github.com/piiton345/calcore/blob/main/src/February.js) (February)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_core["Interpreter<br/>runtime core<br/>[calcore.js]"]
  node_parser["Date parser<br/>token normalizer"]
  node_runloop(("Run loop<br/>execution engine"))
  node_tape[("Tape state<br/>mutable memory")]
  node_output["Output buffer<br/>buffered io"]
  node_flow{{"Control flow<br/>jump logic"}}
  node_clock(("System clock<br/>host time"))
end

subgraph group_opcodes["Opcode months"]
  node_jan["January<br/>io and jumps<br/>[January.js]"]
  node_feb["February<br/>move and convert<br/>[February.js]"]
  node_mar["March<br/>arithmetic<br/>[March.js]"]
  node_apr["April<br/>time and reset<br/>[April.js]"]
end

subgraph group_artifacts["Artifacts"]
  node_package_json["package.json<br/>package manifest<br/>[package.json]"]
  node_dist["dist/calcore.js<br/>built bundle<br/>[calcore.js]"]
end

subgraph group_assets["Examples & spec"]
  node_hello["Hello world<br/>sample program<br/>[Hello_world.clc]"]
  node_example1["Example 1<br/>sample program<br/>[example1.clc]"]
  node_commandref["Command list<br/>language spec<br/>[命令一覧.txt]"]
end

node_package_json -->|"main/bin"| node_dist
node_dist -.->|"built from"| node_core
node_core -->|"tokenizes"| node_parser
node_core -->|"executes"| node_runloop
node_parser -->|"dispatch month"| node_jan
node_parser -->|"dispatch month"| node_feb
node_parser -->|"dispatch month"| node_mar
node_parser -->|"dispatch month"| node_apr
node_runloop -->|"jumps"| node_flow
node_runloop -->|"state"| node_tape
node_runloop -->|"buffers"| node_output
node_jan -->|"print"| node_output
node_jan -->|"read/write"| node_tape
node_jan -->|"branch"| node_flow
node_feb -->|"mutate"| node_tape
node_mar -->|"math on cells"| node_tape
node_apr -->|"query time"| node_clock
node_apr -->|"reset/emit"| node_output
node_hello -->|"runs on"| node_core
node_example1 -->|"runs on"| node_core
node_commandref -->|"defines format"| node_parser

click node_package_json "https://github.com/piiton345/calcore/blob/main/package.json"
click node_core "https://github.com/piiton345/calcore/blob/main/src/calcore.js"
click node_jan "https://github.com/piiton345/calcore/blob/main/src/January.js"
click node_feb "https://github.com/piiton345/calcore/blob/main/src/February.js"
click node_mar "https://github.com/piiton345/calcore/blob/main/src/March.js"
click node_apr "https://github.com/piiton345/calcore/blob/main/src/April.js"
click node_dist "https://github.com/piiton345/calcore/blob/main/dist/calcore.js"
click node_hello "https://github.com/piiton345/calcore/blob/main/example/Hello_world.clc"
click node_example1 "https://github.com/piiton345/calcore/blob/main/example/example1.clc"
click node_commandref "https://github.com/piiton345/calcore/blob/main/src/命令一覧.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core,node_parser,node_runloop,node_tape,node_output,node_flow,node_clock toneBlue
class node_jan,node_feb,node_mar,node_apr toneAmber
class node_package_json,node_dist toneMint
class node_hello,node_example1,node_commandref toneRose
```

## Components

### Runtime

Core interpreter path from parsing to execution and state mutation.

- [Interpreter](https://github.com/piiton345/calcore/blob/main/src/calcore.js): runtime core · Central interpreter and CLI behavior. · `src/calcore.js`
- **Date parser**: token normalizer · Detects the file-wide date convention and normalizes instruction tokens.
- **Run loop**: execution engine · Advances through line-numbered program steps and handles jumps.
- **Tape state**: mutable memory · Cells, pointer, typed values, and indexed storage.
- **Output buffer**: buffered io · Accumulates printed text until flush.
- **Control flow**: jump logic · Non-linear execution via unconditional and conditional line jumps.
- **System clock**: host time · Current-time and date primitives from the host environment.

### Opcode months

Month-based instruction handlers.

- [January](https://github.com/piiton345/calcore/blob/main/src/January.js): io and jumps · Input, output buffering, and jump operations. · `src/January.js`
- [February](https://github.com/piiton345/calcore/blob/main/src/February.js): move and convert · Assignment, pointer movement, copying, and type conversion. · `src/February.js`
- [March](https://github.com/piiton345/calcore/blob/main/src/March.js): arithmetic · Math operations over tape values. · `src/March.js`
- [April](https://github.com/piiton345/calcore/blob/main/src/April.js): time and reset · Output reset and system date/time queries. · `src/April.js`

### Artifacts

Build output and packaged entrypoints.

- [package.json](https://github.com/piiton345/calcore/blob/main/package.json): package manifest · Package metadata and CLI wiring. · `package.json`
- [dist/calcore.js](https://github.com/piiton345/calcore/blob/main/dist/calcore.js): built bundle · Published distributable artifact. · `dist/calcore.js`

### Examples & spec

Sample programs and command reference material.

- [Hello world](https://github.com/piiton345/calcore/blob/main/example/Hello_world.clc): sample program · Example .clc program. · `example/Hello_world.clc`
- [Example 1](https://github.com/piiton345/calcore/blob/main/example/example1.clc): sample program · Additional example .clc program. · `example/example1.clc`
- [Command list](https://github.com/piiton345/calcore/blob/main/src/命令一覧.txt): language spec · Localized command reference for the instruction set. · `src/命令一覧.txt`

## Connections

- package.json → dist/calcore.js: main/bin · Package entry points to the distributed runtime.
- dist/calcore.js → Interpreter: built from · The distributable is produced from the source interpreter.
- Interpreter → Date parser: tokenizes · Normalizes date-encoded instructions before execution.
- Interpreter → Run loop: executes · Drives the sequential program runner.
- Date parser → January: dispatch month · Routes January instructions to the January handler.
- Date parser → February: dispatch month · Routes February instructions to the February handler.
- Date parser → March: dispatch month · Routes March instructions to the March handler.
- Date parser → April: dispatch month · Routes April instructions to the April handler.
- Run loop → Control flow: jumps · Handles non-linear execution and line redirection.
- Run loop → Tape state: state · Reads and mutates tape cells and pointer position.
- Run loop → Output buffer: buffers · Collects printed output before flush.
- January → Output buffer: print · January opcodes append to the output buffer.
- January → Tape state: read/write · January opcodes use tape values for I/O and conditions.
- January → Control flow: branch · January opcodes can redirect execution.
- February → Tape state: mutate · February opcodes move pointers, assign values, and copy cells.
- March → Tape state: math on cells · Arithmetic operates on tape-held values.
- April → System clock: query time · April opcodes read system date and time.
- April → Output buffer: reset/emit · April opcodes can clear or contribute to output behavior.
- Hello world → Interpreter: runs on · Example program exercises the interpreter.
- Example 1 → Interpreter: runs on · Example program exercises the interpreter.
- Command list → Date parser: defines format · Command reference informs token and date decoding.