# thepuppetqueen57/neptune-os architecture

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

- Interactive diagram: https://gitdiagram.com/thepuppetqueen57/neptune-os
- Repository: https://github.com/thepuppetqueen57/neptune-os

## Overview

Neptune OS is a C-based simulated operating system, not a real OS. Its documented structure includes a bootloader and kernel; the visible runtime path is kernel startup, configuration loading, then an interactive terminal where users can run the built-in calculator or Neptubot. The calculator tokenizes expressions and evaluates them using stack-based support code. The sampled files do not establish how boot.c enters the kernel, so that connection is omitted; other unsampled implementation details are not inferred.

Main entry points: [`src/terminal.c`](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/terminal.c) (Command Terminal), [`src/kernel.c`](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/kernel.c) (Kernel), [`src/programs/calculator.h`](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/programs/calculator.h) (Calculator), [`lib/seqft/tokenizer.c`](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/tokenizer.c) (Expression Tokenizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and Kernel"]
  node_boot["Bootloader<br/>[boot.c]"]
  node_kernel["Kernel<br/>[kernel.c]"]
  node_config["Kernel Config<br/>[kernel.json]"]
  node_json["JSON Parser<br/>[cJSON.c]"]
  node_json_api["JSON API<br/>[cJSON.h]"]
end

subgraph group_shell["Interactive Terminal"]
  node_terminal["Command Terminal<br/>[terminal.c]"]
  node_terminal_api["Terminal Interface<br/>[terminal.h]"]
end

subgraph group_programs["Built-in Programs"]
  node_calculator["Calculator<br/>[calculator.h]"]
  node_neptubot["Neptubot<br/>[neptubot.h]"]
end

subgraph group_math["Expression Engine"]
  node_tokenizer["Expression Tokenizer<br/>[tokenizer.c]"]
  node_evaluator["Expression Evaluator<br/>[evaluator.c]"]
  node_stack["Dynamic Stack<br/>[stack.c]"]
  node_common["Math Utilities<br/>[common.c]"]
  node_tokenizer_api["Tokenizer API<br/>[tokenizer.h]"]
  node_evaluator_api["Evaluator API<br/>[evaluator.h]"]
  node_stack_api["Stack API<br/>[stack.h]"]
  node_common_api["Utility API<br/>[common.h]"]
end

node_user(("User"))

node_kernel -->|"reads settings"| node_config
node_kernel -->|"parses config"| node_json
node_kernel -->|"starts shell"| node_terminal
node_kernel -->|"uses API"| node_json_api
node_terminal -->|"reads commands"| node_user
node_terminal -->|"launches"| node_calculator
node_terminal -->|"launches"| node_neptubot
node_terminal -->|"implements"| node_terminal_api
node_calculator -->|"tokenizes expressions"| node_tokenizer
node_calculator -->|"evaluates tokens"| node_evaluator
node_calculator -->|"reports errors"| node_terminal_api
node_tokenizer -->|"uses stacks"| node_stack
node_tokenizer -->|"uses utilities"| node_common
node_evaluator -->|"uses stack API"| node_stack_api
node_evaluator -->|"consumes tokens"| node_tokenizer_api
node_evaluator -->|"uses types"| node_common_api
node_tokenizer -->|"implements"| node_tokenizer_api
node_stack -->|"implements"| node_stack_api
node_common -->|"implements"| node_common_api
node_json -->|"implements"| node_json_api

click node_boot "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/boot.c"
click node_kernel "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/kernel.c"
click node_config "https://github.com/thepuppetqueen57/neptune-os/blob/main/config/kernel.json"
click node_json "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/cJSON.c"
click node_terminal "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/terminal.c"
click node_terminal_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/terminal.h"
click node_calculator "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/programs/calculator.h"
click node_neptubot "https://github.com/thepuppetqueen57/neptune-os/blob/main/src/programs/neptubot.h"
click node_tokenizer "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/tokenizer.c"
click node_evaluator "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/evaluator.c"
click node_stack "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/stack.c"
click node_common "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/common.c"
click node_json_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/cJSON.h"
click node_tokenizer_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/tokenizer.h"
click node_evaluator_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/evaluator.h"
click node_stack_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/stack.h"
click node_common_api "https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/common.h"

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_boot,node_kernel,node_config,node_json,node_json_api,node_user toneBlue
class node_terminal,node_terminal_api toneAmber
class node_calculator,node_neptubot toneMint
class node_tokenizer,node_evaluator,node_stack,node_common,node_tokenizer_api,node_evaluator_api,node_stack_api,node_common_api toneRose
```

## Components

### Startup and Kernel

- [Bootloader](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/boot.c): `src/boot.c`
- [Kernel](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/kernel.c): `src/kernel.c`
- [Kernel Config](https://github.com/thepuppetqueen57/neptune-os/blob/main/config/kernel.json): `config/kernel.json`
- [JSON Parser](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/cJSON.c): `lib/cJSON.c`
- [JSON API](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/cJSON.h): `lib/cJSON.h`

### Interactive Terminal

- [Command Terminal](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/terminal.c): `src/terminal.c`
- [Terminal Interface](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/terminal.h): `src/terminal.h`

### Built-in Programs

- [Calculator](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/programs/calculator.h): `src/programs/calculator.h`
- [Neptubot](https://github.com/thepuppetqueen57/neptune-os/blob/main/src/programs/neptubot.h): `src/programs/neptubot.h`

### Expression Engine

- [Expression Tokenizer](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/tokenizer.c): `lib/seqft/tokenizer.c`
- [Expression Evaluator](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/evaluator.c): `lib/seqft/evaluator.c`
- [Dynamic Stack](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/stack.c): `lib/seqft/stack.c`
- [Math Utilities](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/common.c): `lib/seqft/common.c`
- [Tokenizer API](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/tokenizer.h): `lib/seqft/tokenizer.h`
- [Evaluator API](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/evaluator.h): `lib/seqft/evaluator.h`
- [Stack API](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/stack.h): `lib/seqft/stack.h`
- [Utility API](https://github.com/thepuppetqueen57/neptune-os/blob/main/lib/seqft/common.h): `lib/seqft/common.h`

### Other components

- **User**

## Connections

- Kernel → Kernel Config: reads settings (evidence: `src/kernel.c`)
- Kernel → JSON Parser: parses config (evidence: `src/kernel.c`)
- Kernel → Command Terminal: starts shell (evidence: `src/kernel.c`)
- Kernel → JSON API: uses API (evidence: `src/kernel.c`)
- Command Terminal → User: reads commands (evidence: `src/terminal.c`)
- Command Terminal → Calculator: launches (evidence: `src/terminal.c`)
- Command Terminal → Neptubot: launches (evidence: `src/terminal.c`)
- Command Terminal → Terminal Interface: implements (evidence: `src/terminal.c`)
- Calculator → Expression Tokenizer: tokenizes expressions (evidence: `src/programs/calculator.h`)
- Calculator → Expression Evaluator: evaluates tokens (evidence: `src/programs/calculator.h`)
- Calculator → Terminal Interface: reports errors (evidence: `src/programs/calculator.h`)
- Expression Tokenizer → Dynamic Stack: uses stacks (evidence: `lib/seqft/tokenizer.c`)
- Expression Tokenizer → Math Utilities: uses utilities (evidence: `lib/seqft/tokenizer.c`)
- Expression Evaluator → Stack API: uses stack API
- Expression Evaluator → Tokenizer API: consumes tokens
- Expression Evaluator → Utility API: uses types
- Expression Tokenizer → Tokenizer API: implements (evidence: `lib/seqft/tokenizer.c`)
- Dynamic Stack → Stack API: implements (evidence: `lib/seqft/stack.c`)
- Math Utilities → Utility API: implements (evidence: `lib/seqft/common.c`)
- JSON Parser → JSON API: implements (evidence: `lib/cJSON.c`)
