# palliplease/simpfs architecture

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

- Interactive diagram: https://gitdiagram.com/palliplease/simpfs
- Repository: https://github.com/palliplease/simpfs

## Overview

SimpFS is a command-line block filesystem. A user enters commands in the loop in `main.py`, which dispatches file creation, reading, deletion, listing, storage reporting, and formatting to `FileSystem`; results are displayed in the terminal. The filesystem manages a fixed file table and contiguous data blocks, while `VirtualDisk` reads and writes the backing image in 512-byte blocks. The README also documents help, screen clearing, and exit commands. The map follows the sampled source; it does not assume additional filesystem features such as directories or file updates.

Main entry points: [`filesystem.py`](https://github.com/palliplease/simpfs/blob/main/filesystem.py) (Filesystem), [`main.py`](https://github.com/palliplease/simpfs/blob/main/main.py) (Command loop), [`disk.py`](https://github.com/palliplease/simpfs/blob/main/disk.py) (Virtual disk)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Command interface"]
  node_cli["Command loop<br/>[main.py]"]
  node_create["Create command<br/>[main.py]"]
  node_read["Read command<br/>[main.py]"]
  node_delete["Delete command<br/>[main.py]"]
  node_listing["List command<br/>[main.py]"]
  node_usage["Storage command<br/>[main.py]"]
  node_format["Format command<br/>[main.py]"]
end

subgraph group_filesystem["Filesystem operations"]
  node_fs["Filesystem<br/>[filesystem.py]"]
  node_allocation["Block allocation<br/>[filesystem.py]"]
  node_filetable["File metadata<br/>[filesystem.py]"]
  node_filedata["File data I/O<br/>[filesystem.py]"]
end

subgraph group_storage["Block storage"]
  node_disk["Virtual disk<br/>[disk.py]"]
  node_image[("Disk image")]
end

node_user(("User"))

node_user -->|"enters commands"| node_cli
node_cli -->|"dispatches"| node_create
node_cli -->|"dispatches"| node_read
node_cli -->|"dispatches"| node_delete
node_cli -->|"dispatches"| node_listing
node_cli -->|"dispatches"| node_usage
node_cli -->|"dispatches"| node_format
node_create -->|"creates file"| node_fs
node_read -->|"reads file"| node_fs
node_delete -->|"deletes file"| node_fs
node_listing -->|"lists files"| node_fs
node_usage -->|"measures usage"| node_fs
node_format -->|"formats filesystem"| node_fs
node_fs -->|"finds free blocks"| node_allocation
node_fs -->|"reads and writes entries"| node_filetable
node_fs -->|"reads and writes data"| node_filedata
node_allocation -->|"checks block ranges"| node_filetable
node_filetable -->|"reads and writes blocks"| node_disk
node_filedata -->|"reads and writes blocks"| node_disk
node_fs -->|"writes format header"| node_disk
node_disk -->|"reads and writes"| node_image

click node_cli "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_create "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_read "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_delete "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_listing "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_usage "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_format "https://github.com/palliplease/simpfs/blob/main/main.py"
click node_fs "https://github.com/palliplease/simpfs/blob/main/filesystem.py"
click node_allocation "https://github.com/palliplease/simpfs/blob/main/filesystem.py"
click node_filetable "https://github.com/palliplease/simpfs/blob/main/filesystem.py"
click node_filedata "https://github.com/palliplease/simpfs/blob/main/filesystem.py"
click node_disk "https://github.com/palliplease/simpfs/blob/main/disk.py"

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_cli,node_create,node_read,node_delete,node_listing,node_usage,node_format,node_user toneBlue
class node_fs,node_allocation,node_filetable,node_filedata toneAmber
class node_disk,node_image toneMint
```

## Components

### Command interface

- [Command loop](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [Create command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [Read command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [Delete command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [List command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [Storage command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`
- [Format command](https://github.com/palliplease/simpfs/blob/main/main.py): `main.py`

### Filesystem operations

- [Filesystem](https://github.com/palliplease/simpfs/blob/main/filesystem.py): `filesystem.py`
- [Block allocation](https://github.com/palliplease/simpfs/blob/main/filesystem.py): `filesystem.py`
- [File metadata](https://github.com/palliplease/simpfs/blob/main/filesystem.py): `filesystem.py`
- [File data I/O](https://github.com/palliplease/simpfs/blob/main/filesystem.py): `filesystem.py`

### Block storage

- [Virtual disk](https://github.com/palliplease/simpfs/blob/main/disk.py): `disk.py`
- **Disk image**

### Other components

- **User**

## Connections

- User → Command loop: enters commands
- Command loop → Create command: dispatches
- Command loop → Read command: dispatches
- Command loop → Delete command: dispatches
- Command loop → List command: dispatches
- Command loop → Storage command: dispatches
- Command loop → Format command: dispatches
- Create command → Filesystem: creates file
- Read command → Filesystem: reads file
- Delete command → Filesystem: deletes file
- List command → Filesystem: lists files
- Storage command → Filesystem: measures usage
- Format command → Filesystem: formats filesystem
- Filesystem → Block allocation: finds free blocks
- Filesystem → File metadata: reads and writes entries
- Filesystem → File data I/O: reads and writes data
- Block allocation → File metadata: checks block ranges
- File metadata → Virtual disk: reads and writes blocks
- File data I/O → Virtual disk: reads and writes blocks
- Filesystem → Virtual disk: writes format header
- Virtual disk → Disk image: reads and writes