Coding Adventures is a learning-first monorepo for understanding computers by building the layers ourselves: logic gates and processors, parsers and virtual machines, compilers and runtimes, storage engines, UI systems, and complete applications.

It is part computing-stack curriculum, part polyglot package laboratory, part language-platform project, and part application sandbox. The point is not merely to collect implementations. The point is to make each idea inspectable, testable, comparable across languages, and teachable.

The repository has four reinforcing layers:

specs       define the intended design and contracts
learning    explains why the ideas work
packages    implements the reusable pieces
programs    composes those pieces into tools, demos, and applications

Tests, conformance suites, and the dependency-aware build system connect all four. A shared package change is tested not only in isolation but also through the downstream packages affected by it.

The repository changes quickly. This README describes the durable architecture and current direction; it deliberately avoids a hand-maintained package inventory. Run the package parity report for a live cross-language view.

These counts are a dated orientation point, not release promises. The generated reports and the repository tree remain authoritative as the monorepo changes. The busiest current integration threads are Mosaic's native UI emitters, task-app's structured project surfaces, HTML parser conformance, and the human-language curriculum and book pipeline.

The north-star is a language platform where a language author supplies grammar files and one frontend, then reuses shared tooling, optimizers, runtimes, and backends.

source
  |
  +--> .tokens + .grammar --> generated lexer/parser --> AST/CST
                                                        |
                                      +-----------------+-----------------+
                                      |                                   |
                                      v                                   v
                               IIR: execution hub                  SIR: semantic hub
                                      |                                   |
                   +------------------+------------------+       +--------+---------+
                   |        |        |        |         |       |        |         |
                 native    LLVM     WASM     JVM/CLR    VM/JIT  Python   Ruby   JS/TS/Go/
                                                                            Rust/C

• IIR is the lower, typed execution representation. It feeds native, LLVM, WASM, JVM, CLR, BEAM, VM, JIT, and retro-CPU targets.
• SIR is the higher semantic representation. It preserves source-language concepts and emits runnable Python, Ruby, JavaScript, TypeScript, Go, Rust, and C.
• The planned IIR/SIR bridges turn compilation and transpilation into routes through one stage graph instead of bespoke language-to-language projects.

The execution matrix runs real programs across backends and compares results, so a backend is not considered supported merely because it accepts the IR. See the LANG-VM platform vision, generic language pipeline, IIR, and Semantic IR.

Another central thread builds computation from physical and logical primitives:

transistors --> gates --> arithmetic --> CPU/microarchitecture --> ISA
     --> assembler --> compiler/runtime --> language --> application

The repo includes transistor and gate models, ALUs, caches, branch prediction, pipelines, processor cores, and simulators for architectures including ARM, ARM1, RISC-V, WASM, Intel 4004/8008, JVM, and CLR. Several browser visualizers make those layers interactive.

Start with the architecture overview, deep CPU architecture, and computing-stack learning guide.

The language directories are not identical snapshots. Rust is the broadest implementation surface and often carries systems-facing reference work, native backends, and shared engines first. Python, TypeScript, Go, Ruby, and the other ecosystems contain a mix of:

• independent implementations of the same concept;
• conformance mirrors ported from a reference;
• native bindings around shared Rust cores;
• platform-specific implementations and applications;
• educational ports used to compare language design and tooling.

The parity reporter groups those implementations by concept, highlights high-consensus packages, and tracks single-language work without pretending every package must exist everywhere.

The repository covers the whole path from source text to execution:

• shared token and grammar formats;
• generated lexers and parsers;
• ASTs, type checkers, formatters, LSP and DAP infrastructure;
• bytecode compilers, VMs, JIT/AOT infrastructure, and native backends;
• backend-independent IR validation, lowering, optimization, and conformance;
• historical and experimental languages including BASIC, ALGOL, Nib, Twig, APL, FLOW-MATIC, COBOL-60, MATLAB/Octave, Wolfram, Macsyma/Maxima, and more;
• JavaScript parsing and Closure Compiler compatibility work.

The FLOW-MATIC and COBOL code-generation track is building toward the intended reuse model: frontends target IIR to run across execution backends and SIR to transpile across source backends. Math-language work adds array/matrix and symbolic domains to the same semantic hub. See PL09 code generation and HML01 math languages to Semantic IR.

The runtime stack includes a language-neutral tagged dynamic-value substrate, boxing/unboxing, heap values, truthiness, and dynamic arithmetic. The native AOT path now includes precise roots, generational collection, compaction, incremental collection, variable-length reference arrays, and GC-managed Twig lists, closures, records, unions, and strings.

The numeric and symbolic side includes arbitrary-precision integers, rationals, decimals and binary floats; computer algebra packages; rewrite systems; constraint solving; logic programming; statistics; and the ADJ rule/formula language. Exactness and explicit lossy conversions are treated as design properties rather than incidental implementation details.

See the dynamic-value substrate and Twig native-AOT GC coverage.

ADJ is a typed rule, fact, table, and formula system for reasoning that can be inspected and replayed. Its packages cover exact quantities, bidirectional formulas, rule adjudication, provenance, uncertainty, explanation rendering, and state-machine composition. Formula and fact libraries exercise the same engine across physics, chemistry, biology, medicine, and other domains.

The broader adjudication framework separates source decomposition, structural coverage, polarity and modality checks, adversarial verification, clarification, execution, and audit trails. This makes a conclusion more than an opaque answer: the system can show which facts and rules fired, what evidence was missing, and how the result was derived.

See the ADJ overview, rule substrate, and formula libraries.

The SQL stack is deliberately decomposed:

SQL text --> lexer --> parser --> planner --> optimizer --> codegen --> SQL VM
                                                                   |
                                                                   v
                                                            Backend trait
                                                                   |
                                                   in-memory or SQLite files

This supports both a composable query engine and a path toward a byte-compatible, from-scratch SQLite replacement. Work covers SQL semantics, query planning, indexes, transactions, SQLite file pages/B-trees, and differential checks against real SQLite.

See the full mini-SQLite conformance roadmap and storage-sqlite.

Package families include trees, tries, graphs, heaps, probabilistic structures, filesystems, virtual memory, processes, event loops, reactors, IPC, TCP/HTTP, RPC, device protocols, and operating-system abstractions.

Security and encoding work includes hashes, HMAC, HKDF, PBKDF2, scrypt, AES, ChaCha20-Poly1305, Ed25519, X25519, compression formats, image/document decoders, barcodes, and strict bounds-checked binary parsing.

The C and C++ lanes compile pure-ISO ports under GCC, Clang, Apple Clang, and MSVC with strict conformance flags. See the C/C++ multi-compiler lane. OCaml is a known emerging implementation lane governed by OCAML01; its packages remain outside the established parity denominator until the scaffold, resolver, capability, build-tool, package, and three-platform promotion gates pass. The two scaffold-generator front doors implement the byte-stable library and program contract in OCAML02, including exact direct opam/Dune constraints, Alcotest, formatting, coverage, and capability profiles. OCAML03 supplies the CI-toolchain gate with digest-checked per-platform solver locks, installed-package receipts, and a pinned three-platform workflow that performs both a fresh-solve comparison and separate locked execution of the two scaffold kinds. Hosted-runner image values are recorded as diagnostics, not as immutable host attestations. The parity report's JSON schema is version 3, and CSV consumers must select presence columns by header name because recognized emerging lanes extend the matrix.

The content/rendering stack includes CommonMark, GFM, AsciiDoc, document ASTs, HTML sanitization, Office file formats, font parsing, image codecs, layout, draw/paint instruction systems, and native/GPU rendering backends.

Mosaic is the compile-time UI language. A typed UI description can be emitted to web components, React, SwiftUI, Jetpack Compose, Flutter, Qt, XAML, HTML, and paint-oriented backends. The same pattern lets a headless Rust engine power multiple native and web hosts without duplicating product behavior.

See the Mosaic overview and Mosaic compiler pipeline.

Forme is the repository's universal authoring pipeline: typed, capability-aware stages turn content into web pages, documentation sites, feeds, search indexes, and deployment artifacts. Its 63 TypeScript packages now cover the kernel and orchestrator, filesystem and Markdown sources, routing and collection, transformations, Style IR, HTML/AOT emitters, metadata, sitemaps, feeds, fingerprinted assets, an in-memory live-preview server, and a complete searchable documentation-site cluster.

Product sites and focused demos prove the composition model:

• code/sites/landing-page generates this repository's root Pages surface from declarative content through a seven-stage routed Style IR and asset pipeline;
• code/sites/blog runs a ten-stage routed DAG that emits articles, a themed index, RSS, Atom, sitemap, and fingerprinted local assets;
• forme-hello-world runs the smallest source → parse → render → emit pipeline;
• forme-doc-demo builds a multi-page documentation site with navigation, a table of contents, syntax highlighting, and browser search.

The headless build path and general build/check/clean/watch CLI work, including loopback preview, live reload, last-good-output behavior, and deterministic cross-process reuse of unchanged pure stage invocations through a configured project cache. Forme is not yet a turnkey site generator: the remaining product layer includes external-state affected-set scheduling, bounded concurrent streaming, a reconciled specification map, the plugin host and OS sandboxes, interactivity, the authoring shell, and the deploy runner. The checked-in completion roadmap tracks that path and the gaps discovered while dogfooding both live sites.

Start with the Forme vision, kernel, orchestrator, and Style IR.

Programs are integration surfaces, not just toy examples:

• Engram combines a shared Rust core, native/WASM bridges, Mosaic UI work, Electron/browser hosts, and Anki compatibility.
• task-app is applying the same architecture to a general task/project engine. Its pure task-core model, operations/formula API, project switching, and structured task UI are landing toward one model exposed as checklist, todo, kanban, Gantt, flowchart, and table views with scheduling.
• Venture composes the repository's URL, HTTP, HTML, layout, paint, image, windowing, and platform bridges into a native educational web browser. The macOS host now supports navigation, links, and keyboard and wheel scrolling.
• smart-home provides a local-first supervised runtime for normalized device state, commands, automations, policy, and audit. Hue, Zigbee, and Z-Wave work exercise the adapter boundary without making one vendor protocol the core.
• language-ladder turns the human-language curriculum into an interactive browser for concepts, scripts, syllabaries, lessons, and review progress.
• VisiCalc exercises spreadsheet, UI, and multi-host compilation paths.
• Journal, checklist, browser-extension, language-tooling, IRC, ML, document, and hardware visualizer programs test other package families end to end.

See Engram and the task-app overview, Venture, and the smart-home runtime.

.
|-- code/
|   |-- benchmarks/   reproducible performance experiments
|   |-- datasets/     shared data used by packages and programs
|   |-- fixtures/     shared binary/text fixtures and sample inputs
|   |-- grammars/     canonical .tokens and .grammar sources
|   |-- learning/     plain-language teaching material
|   |-- packages/     reusable libraries grouped by ecosystem
|   |-- programs/     executables, demos, apps, and visualizers
|   |-- scripts/      repository-wide generation, reporting, and safety tools
|   |-- sites/        website source/content
|   \-- specs/        architecture, package, and roadmap specifications
|-- .github/workflows CI, CodeQL, safety, publishing, releases, and deployment
|-- CHANGELOG.md      monorepo-level notable changes
|-- CLAUDE.md         repository policy and working conventions
\-- lessons.md        accumulated engineering failures and durable fixes

Package inventory buckets currently recognize C, C++, C#, Dart, Elixir, F#, Go, Haskell, Java, Kotlin, Lua, OCaml, Perl, Python, Ruby, Rust, Swift, TypeScript, and WebAssembly. C, C++, and OCaml are emerging rather than established parity lanes. Mosaic and Twig are domain-language buckets; Starlark is used for build configuration rather than as an implementation ecosystem.

The primary build tool is the Go program in code/programs/go/build-tool. It:

1. discovers packages through BUILD files;
2. evaluates Starlark build definitions where used;
3. reads ecosystem metadata such as Cargo, Go, Python, npm, Gradle, Swift, Ruby, Elixir, Dart, Haskell, and .NET manifests;
4. constructs the cross-language dependency graph;
5. maps a Git diff to changed packages and all transitive dependents;
6. validates declared dependencies and standalone build prerequisites;
7. schedules independent packages concurrently;
8. emits reusable and sharded build plans for CI.

BUILD_windows files provide legacy/platform-specific Windows commands while the repository migrates more rules to OS-aware Starlark definitions. required_capabilities.json files declare runtime/toolchain requirements for packages that need capability-aware execution.

The root mise.toml pins the local toolchain baseline:

• Cabal 3.16.1.0 and GHC 9.14.1;
• Dart latest;
• Go latest;
• Gradle 8.14 and Kotlin 2.1.20;
• Lua 5.4;
• Python 3.12;
• Ruby 3.4;
• Rust stable.

CI installs its own explicit versions and does not depend on mise.

On macOS/Linux:

cd code/programs/go/build-tool
go build -o ../../../../build-tool .
cd ../../../..
./build-tool -root . -diff-base origin/main -dry-run

On Windows:

cd code\programs\go\build-tool
go build -o ..\..\..\..\build-tool.exe .
cd ..\..\..\..
.\build-tool.exe -root . -diff-base origin/main -dry-run

The diff-based plan compares committed branch history with origin/main. Commit or otherwise verify the intended diff before treating its affected set as authoritative. Use the package's own BUILD/test command for fast, uncommitted iteration.

Useful repository checks:

# Validate and show the affected plan without running it.
./build-tool -root . -diff-base origin/main -dry-run -validate-build-files

# Show which CI toolchains the branch needs.
./build-tool -root . -diff-base origin/main -detect-languages

# Inspect cross-language coverage and reject naming collisions.
python code/scripts/package_parity_report.py --fail-on-collisions

# Classify Python uv fronts that cannot repeat in the same checkout.
python code/scripts/python_uv_build_front_audit.py --format markdown

# Regenerate the package-to-learning coverage backlog.
python code/scripts/learning_coverage_report.py --output code/learning/COVERAGE.md

# Test the build tool itself.
cd code/programs/go/build-tool && go test ./...

The parity report distinguishes established implementation lanes from emerging ones. Emerging OCaml packages are visible in JSON, Markdown, and CSV output but do not create missing slots until the explicit promotion contract is completed.

The main CI workflow uses the same build planner:

• branch pushes build affected packages;
• pull requests validate affected work across Linux, macOS, and Windows when the selected languages require those runners;
• pushes to main create a forced five-shard full-build plan;
• Rust packages run per-package Clippy with warnings denied;
• CodeQL covers JavaScript/TypeScript, Python, Ruby, Go, and Swift;
• Miri blocks on unsafe-bearing runtime crates, with deeper integration checks running after merge and nightly;
• dedicated workflows test Rust-to-Node and Rust-to-Python native matrices;
• publish, release, and GitHub Pages workflows ship selected artifacts.

Packages are expected to carry tests, a README, a changelog, and publishable ecosystem metadata. Libraries target at least 80% coverage, with 95% preferred for most package code.

Read CLAUDE.md and lessons.md before making changes. The recurring workflow is:

1. Fetch the latest origin/main.
2. Create a feature branch, preferably in a fresh worktree.
3. Write or refine the specification.
4. Add or update the relevant learning material.
5. Add tests before or alongside implementation.
6. Implement the smallest coherent change.
7. Update package README and CHANGELOG files.
8. Run the package tests and the affected-package plan.
9. Review the complete branch diff, including generated files and downstream consumers.
10. Run the required security review before pushing.

Important conventions:

• Do not commit directly to main.
• Shared grammar sources are authoritative; regenerate compiled grammars rather than hand-editing generated files.
• BUILD commands must be standalone and include all transitive local prerequisites in dependency order.
• New package scaffolding should go through the scaffold generator.
• Stage explicit files and keep build artifacts out of commits.
• If implementation and specification diverge, update the spec and document the decision.

Choose a path based on what you want to understand:

The learning index collects the teaching-oriented material by subject.

Selected programs are deployed to adhithyan15.github.io/coding-adventures:

• Arithmetic — adders, ALU, two's-complement, multiplication, and CPU steps;
• ARM1 — registers, pipeline, barrel shifter, and memory views;
• Busicom and ENIAC — interactive historical machines;
• Transistors, Logic Gates, and Electronics Visualizers — inspectable hardware layers;
• Nib, Lattice, and CommonMark — language and compiler playgrounds;
• Code 39 — barcode rendering through the repository's draw-instruction pipeline;
• Engram and Engram Docs — a spaced-repetition application and its documentation;
• ML Learning Lab — browser-runnable machine-learning demonstrations;
• Language Ladder and the human-language book catalog — interactive lessons and generated books;
• Forme notes — articles produced by the repository's own authoring pipeline.

The Journal application remains active in the repository, but its Pages route is currently unavailable and is intentionally not linked as a live surface.

Everything in this repository is copyrighted to Adhithya Rajasekaran. Individual packages may be licensed separately.