# kichipoe/learn-c-core architecture

> Architecture diagram of the GitHub repository kichipoe/learn-c-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kichipoe/learn-c-core
- Repository: https://github.com/kichipoe/learn-c-core

## Overview

#### Purpose and Scope
This is a documentation-first C learning repository. Its implemented scope is currently Level 0: compiler toolchain, compilation behavior, debugging, command-line arguments, and a small modular calculator. The repository is not a unified application; each directory contains independently compiled learning exercises.

#### Entry Points and Execution Model
Most examples are standalone C executables entered through `main`. Primary executable sources include:
- `Level-0-Toolchain/1-dev-env/main.c`
- `Level-0-Toolchain/7-cli-program/main.c`
- `Level-0-Toolchain/8-mycalc/src/main.c`

Programs are compiled externally with a C compiler; no build system, runtime service, deployment target, or infrastructure definition is present.

#### Curriculum as the Top-Level Architecture
The root documentation defines a staged progression from toolchain fundamentals through production-quality C. The current implemented stage is represented by:
- `ROADMAP.md`
- `Level-0-Toolchain/LEARNING.md`
- `Level-0-Toolchain/PROJECT.md`

Level 0 is organized as numbered, isolated stages. This makes experimentation and intentional failures first-class learning artifacts rather than shared production modules.

#### Toolchain and Compilation Stages
The early directories establish the C development lifecycle:
- Environment and return-value behavior: `Level-0-Toolchain/1-dev-env/main.c`, `Level-0-Toolchain/1-dev-env/no-main-return.c`
- Minimal program structure and required headers/entry point: `Level-0-Toolchain/2-my-first-program/main.c`, `Level-0-Toolchain/2-my-first-program/without-main.c`
- Compilation pipeline and compiler flags: `Level-0-Toolchain/3-compilation-pipeline/main.c`, `Level-0-Toolchain/4-compiler-flags/main.c`

Control flow is source file → compiler/preprocessor/assembler/linker workflow → native executable. Compiler diagnostics are part of the expected output of several stages.

#### Failure and Debugging Boundary
Deliberately invalid programs isolate major compiler/linker failure classes:
- `Level-0-Toolchain/5-complier-errors/syntax-error.c`
- `Level-0-Toolchain/5-complier-errors/unknown-func.c`
- `Level-0-Toolchain/5-complier-errors/linker-error.c`

Debugging is then treated as a separate workflow around a runnable program in `Level-0-Toolchain/6-Debuging/main.c`. These examples should remain independently compiled because their intended behavior includes compile or link failure.

#### Command-Line Interface Exercise
`Level-0-Toolchain/7-cli-program/main.c` is the explicit CLI boundary. Its input arrives through the conventional C process arguments (`argc`/`argv`), and its output is terminal-oriented. It has no persistence, network, or external API integration.

#### Modular Calculator Project
The calculator is the most application-like component and demonstrates C module boundaries:
- Public interface: `Level-0-Toolchain/8-mycalc/include/calculator.h`
- Arithmetic implementation: `Level-0-Toolchain/8-mycalc/src/calculator.c`
- CLI/application orchestration: `Level-0-Toolchain/8-mycalc/src/main.c`

Its primary flow is user/process input → `main` parses or dispatches operation requests → calculator API calls → arithmetic result or error handling → terminal output. The header separates declaration/API contract from implementation, and linking must combine `main.c` with `calculator.c`.

#### Documentation and Learning Feedback Loop
Repository-wide planning and retrospective records provide the non-code control layer:
- `README.md`
- `NOTES.md`
- `MISTAKES.md`

The intended workflow is learn a concept, run an experiment or small program, record findings and mistakes, then expand into a project. No external services or nonstandard runtime dependencies are evidenced; the material runtime is a native C executable plus a local C compiler/debugger toolchain.

Main entry points: [`Level-0-Toolchain/LEARNING.md`](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/LEARNING.md) (Level 0 guides), [`Level-0-Toolchain/8-mycalc/src/main.c`](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/main.c) (Calculator CLI main), [`Level-0-Toolchain/8-mycalc/src/calculator.c`](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/calculator.c) (Arithmetic implementation), [`ROADMAP.md`](https://github.com/kichipoe/learn-c-core/blob/main/ROADMAP.md) (Roadmap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Learning Control"]
  node_roadmap["Roadmap<br/>curriculum<br/>[ROADMAP.md]"]
  node_level_docs["Level 0 guides<br/>documentation<br/>[LEARNING.md]"]
  node_learning_records["Learning records<br/>documentation<br/>[README.md]"]
end

subgraph group_stages["Level 0 Exercises"]
  node_dev_env["Environment examples<br/>C sources<br/>[main.c]"]
  node_program_structure["Program structure<br/>C sources<br/>[main.c]"]
  node_compile_pipeline["Compilation pipeline<br/>C source<br/>[main.c]"]
  node_compiler_flags["Compiler flags<br/>C source<br/>[main.c]"]
  node_intentional_failures["Intentional failures<br/>invalid C sources<br/>[syntax-error.c]"]
  node_debugging["Debugging exercise<br/>C executable source<br/>[main.c]"]
  node_cli_exercise["CLI exercise<br/>C executable source<br/>[main.c]"]
end

subgraph group_calculator["Modular Calculator"]
  node_calc_main["Calculator CLI main<br/>C application source<br/>[main.c]"]
  node_calc_api["Calculator API<br/>C header<br/>[calculator.h]"]
  node_calc_impl["Arithmetic implementation<br/>C module<br/>[calculator.c]"]
end

node_toolchain{{"C toolchain<br/>external toolchain"}}
node_native_executables["Native executables<br/>local process"]

node_roadmap -->|"defines Level 0"| node_level_docs
node_level_docs -->|"organizes"| node_dev_env
node_level_docs -->|"organizes"| node_program_structure
node_level_docs -->|"organizes"| node_compile_pipeline
node_level_docs -->|"organizes"| node_compiler_flags
node_level_docs -->|"organizes"| node_intentional_failures
node_level_docs -->|"organizes"| node_debugging
node_level_docs -->|"organizes"| node_cli_exercise
node_level_docs -->|"culminates in"| node_calc_main
node_learning_records -.->|"records learning around"| node_roadmap
node_dev_env -->|"compiled by"| node_toolchain
node_program_structure -->|"compiled by"| node_toolchain
node_compile_pipeline -->|"shows stages of"| node_toolchain
node_compiler_flags -->|"configures"| node_toolchain
node_intentional_failures -->|"produces diagnostics from"| node_toolchain
node_debugging -->|"debugged with"| node_toolchain
node_cli_exercise -->|"runs as"| node_native_executables
node_calc_main -->|"calls"| node_calc_api
node_calc_impl -->|"implements"| node_calc_api
node_calc_main -->|"linked with implementation by"| node_toolchain
node_calc_impl -->|"compiled and linked by"| node_toolchain
node_toolchain -->|"produces"| node_native_executables
node_calc_main -->|"terminal input and output"| node_native_executables

click node_roadmap "https://github.com/kichipoe/learn-c-core/blob/main/ROADMAP.md"
click node_level_docs "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/LEARNING.md"
click node_learning_records "https://github.com/kichipoe/learn-c-core/blob/main/README.md"
click node_dev_env "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/1-dev-env/main.c"
click node_program_structure "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/2-my-first-program/main.c"
click node_compile_pipeline "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/3-compilation-pipeline/main.c"
click node_compiler_flags "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/4-compiler-flags/main.c"
click node_intentional_failures "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/5-complier-errors/syntax-error.c"
click node_debugging "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/6-Debuging/main.c"
click node_cli_exercise "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/7-cli-program/main.c"
click node_calc_main "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/main.c"
click node_calc_api "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/include/calculator.h"
click node_calc_impl "https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/calculator.c"

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_roadmap,node_level_docs,node_learning_records toneBlue
class node_dev_env,node_program_structure,node_compile_pipeline,node_compiler_flags,node_intentional_failures,node_debugging,node_cli_exercise toneAmber
class node_calc_main,node_calc_api,node_calc_impl toneMint
class node_toolchain,node_native_executables toneNeutral
```

## Components

### Learning Control

Repository planning and learning records.

- [Roadmap](https://github.com/kichipoe/learn-c-core/blob/main/ROADMAP.md): curriculum · Defines the staged C learning progression. · `ROADMAP.md`
- [Level 0 guides](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/LEARNING.md): documentation · Defines Level 0 scope and project expectations. · `Level-0-Toolchain/LEARNING.md`
- [Learning records](https://github.com/kichipoe/learn-c-core/blob/main/README.md): documentation · Captures repository context, notes, and mistakes. · `README.md`

### Level 0 Exercises

Independently compiled toolchain lessons.

- [Environment examples](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/1-dev-env/main.c): C sources · Return-value and environment experiments. · `Level-0-Toolchain/1-dev-env/main.c`
- [Program structure](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/2-my-first-program/main.c): C sources · Entry-point and header requirements. · `Level-0-Toolchain/2-my-first-program/main.c`
- [Compilation pipeline](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/3-compilation-pipeline/main.c): C source · Demonstrates preprocessing through linking. · `Level-0-Toolchain/3-compilation-pipeline/main.c`
- [Compiler flags](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/4-compiler-flags/main.c): C source · Experiments with compiler options and diagnostics. · `Level-0-Toolchain/4-compiler-flags/main.c`
- [Intentional failures](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/5-complier-errors/syntax-error.c): invalid C sources · Separates syntax, unresolved-symbol, and linker failures. · `Level-0-Toolchain/5-complier-errors/syntax-error.c`
- [Debugging exercise](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/6-Debuging/main.c): C executable source · Runnable program used with the debugger. · `Level-0-Toolchain/6-Debuging/main.c`
- [CLI exercise](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/7-cli-program/main.c): C executable source · Consumes argc/argv and writes terminal output. · `Level-0-Toolchain/7-cli-program/main.c`

### Modular Calculator

The application-like Level 0 project.

- [Calculator CLI main](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/main.c): C application source · Parses requests and renders results or errors. · `Level-0-Toolchain/8-mycalc/src/main.c`
- [Calculator API](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/include/calculator.h): C header · Public arithmetic module contract. · `Level-0-Toolchain/8-mycalc/include/calculator.h`
- [Arithmetic implementation](https://github.com/kichipoe/learn-c-core/blob/main/Level-0-Toolchain/8-mycalc/src/calculator.c): C module · Implements calculator operations. · `Level-0-Toolchain/8-mycalc/src/calculator.c`

### Other components

- **C toolchain**: external toolchain · Compiler and debugger drive local experiments.
- **Native executables**: local process · Standalone binaries run in the local terminal.

## Connections

- Roadmap → Level 0 guides: defines Level 0
- Level 0 guides → Environment examples: organizes
- Level 0 guides → Program structure: organizes
- Level 0 guides → Compilation pipeline: organizes
- Level 0 guides → Compiler flags: organizes
- Level 0 guides → Intentional failures: organizes
- Level 0 guides → Debugging exercise: organizes
- Level 0 guides → CLI exercise: organizes
- Level 0 guides → Calculator CLI main: culminates in
- Learning records → Roadmap: records learning around
- Environment examples → C toolchain: compiled by
- Program structure → C toolchain: compiled by
- Compilation pipeline → C toolchain: shows stages of
- Compiler flags → C toolchain: configures
- Intentional failures → C toolchain: produces diagnostics from
- Debugging exercise → C toolchain: debugged with
- CLI exercise → Native executables: runs as
- Calculator CLI main → Calculator API: calls
- Arithmetic implementation → Calculator API: implements
- Calculator CLI main → C toolchain: linked with implementation by
- Arithmetic implementation → C toolchain: compiled and linked by
- C toolchain → Native executables: produces
- Calculator CLI main → Native executables: terminal input and output