# Project Structure

Overview of the ModuOS source code organization.

## Directory Layout

```
ModuOS/
├── buildenv/              # Docker build environment
│   └── Dockerfile
├── include/               # Header files
│   └── moduos/
│       ├── arch/          # Architecture-specific headers
│       ├── drivers/       # Driver headers
│       ├── fs/            # Filesystem headers
│       └── kernel/        # Kernel headers
├── src/                   # Source code
│   ├── arch/              # Architecture-specific code
│   ├── drivers/           # Hardware drivers
│   ├── fs/                # Filesystem implementations
│   └── kernel/            # Core kernel
├── targets/               # Build targets
│   └── AMD64/
│       ├── iso/           # ISO filesystem layout
│       └── linker.ld      # Linker script
├── userland/              # User-space programs
├── LICENSES/              # Third-party licenses
├── Makefile               # Build system
├── run.bat                # Build and run script
└── readme.md              # Project README
```

## Source Organization

### Architecture Layer (`src/arch/AMD64/`)

```
arch/AMD64/
├── boot/                  # Boot code
│   ├── header.asm         # Multiboot2 header
│   ├── main.asm           # 32-bit bootstrap
│   └── main64.asm         # 64-bit entry
├── interrupts/            # Interrupt handling
│   ├── fault.asm          # CPU exception handlers
│   ├── idt.c              # IDT setup
│   ├── irq.c              # Hardware interrupts
│   ├── isr.asm            # Interrupt service routines
│   ├── pic.c              # PIC driver
│   └── timer.c            # PIT timer
└── syscall/               # System call handling
    ├── context_switch.asm # Process switching
    └── syscall_entry.asm  # Syscall entry point
```

### Kernel Core (`src/kernel/`)

```
kernel/
├── kernel.c               # Main kernel entry
├── panic.c                # Kernel panic handler
├── exec.c                 # Program execution
├── fault.c                # Fault handling
├── md64api.c              # System API
├── memory/                # Memory management
│   ├── kheap.c            # Kernel heap
│   ├── memory.c           # Memory initialization
│   ├── multiboot2.c       # Multiboot2 parsing
│   ├── paging.c           # Virtual memory
│   ├── phys.c             # Physical allocator
│   └── string.c           # String operations
├── process/               # Process management
│   └── process.c          # Scheduler and processes
├── syscall/               # System calls
│   └── syscall.c          # Syscall dispatcher
├── shell/                 # Built-in shell
│   ├── zenith4.c          # Main shell
│   ├── helpers.c          # Shell utilities
│   ├── art.c              # ASCII art
│   └── legacy/
│       └── MSDOS.c        # Legacy DOS commands
├── applications/          # Built-in apps
│   └── rl-clock.c         # Real-time clock app
├── games/                 # Built-in games
│   ├── game_menu.c        # Game selector
│   ├── eatfruit.c         # Snake game
│   ├── mine_sweep.c       # Minesweeper
│   ├── RaycasterFPS.c     # FPS game
│   ├── stackblocks.c      # Puzzle game
│   └── verticalpingpong.c # Pong game
├── COM/                   # Serial port
│   └── com.c              # COM driver
├── events/                # Event system
│   └── events.c           # Event handling
├── io/                    # I/O operations
│   └── io.c               # Port I/O
└── loader/                # Program loader
    └── elf.c              # ELF loader
```

### Drivers (`src/drivers/`)

```
drivers/
├── Drive/                 # Storage drivers
│   ├── vDrive.c           # Virtual drive layer
│   ├── ATA/
│   │   ├── ata.c          # ATA/IDE driver
│   │   └── atapi.c        # ATAPI (CD-ROM)
│   └── SATA/
│       ├── AHCI.c         # AHCI controller
│       └── SATA.c         # SATA driver
├── graphics/              # Built-in graphics drivers
│   ├── VGA.c              # VGA text mode
│   └── fb_console.c       # Framebuffer console (text on pixel framebuffer)

modules/
├── QXL/                    # QXL SQRM GPU driver
├── VMSVGA/                 # VMware SVGA SQRM GPU driver
└── md_vga_compatible_display_sqrm.c  # VGA-compatible SQRM GPU driver (fallback)
├── input/                 # Input drivers
│   ├── input.c            # Input abstraction
│   └── ps2/
│       └── ps2.c          # PS/2 keyboard/mouse
├── PCI/                   # PCI subsystem
│   └── pci.c              # PCI enumeration
├── power/                 # Power management
│   └── ACPI.c             # ACPI driver
├── Time/                  # Time/clock
│   └── RTC.c              # Real-time clock
└── USB/                   # USB subsystem
    ├── usb.c              # USB core
    ├── Classes/
    │   ├── hid.c          # HID devices
    │   └── hub.c          # USB hubs
    └── Controllers/
        ├── uhci.c         # UHCI controller
        ├── ohci.c         # OHCI controller
        └── ehci.c         # EHCI controller
```

### File Systems (`src/fs/`)

```
fs/
├── fs.c                   # VFS layer
├── fd.c                   # File descriptors
├── hvfs.c                 # High-level VFS
├── DOS/
│   └── FAT32/
│       └── fat32.c        # FAT32 implementation
└── ISOFS/
    └── iso9660.c          # ISO9660 (CD-ROM)
```

## Header Organization

Headers follow the same structure as source files:

```
include/moduos/
├── arch/AMD64/interrupts/
├── drivers/
│   ├── Drive/
│   ├── graphics/
│   ├── input/
│   ├── PCI/
│   ├── power/
│   ├── Time/
│   └── USB/
├── fs/
└── kernel/
    ├── memory/
    ├── process/
    ├── shell/
    └── syscall/
```

## Naming Conventions

### Files

- **C files**: lowercase with underscores (`memory.c`, `fat32.c`)
- **Assembly**: lowercase with underscores (`main.asm`, `isr.asm`)
- **Headers**: lowercase matching C file (`memory.h`)

### Functions

- **Public API**: `subsystem_operation()` format
  - Example: `process_create()`, `fs_mount_drive()`
- **Private/Static**: `_internal_function()` or `static`
- **Assembly**: `asm_function_name`

### Types

- **Structs**: `name_t` suffix
  - Example: `process_t`, `fs_mount_t`
- **Enums**: `name_t` suffix
  - Example: `process_state_t`, `fs_type_t`

### Constants

- **Macros**: `UPPER_CASE_SNAKE`
  - Example: `MAX_PROCESSES`, `PAGE_SIZE`

## Build Targets

### ISO Layout

```
targets/AMD64/iso/
├── boot/grub/
│   ├── grub.cfg           # GRUB configuration
│   └── *.pf2              # Fonts
├── Apps/                  # User programs
│   ├── cat.sqr
│   ├── echo.sqr
│   └── sh.sqr
├── ModuOS/
│   ├── System64/
│   │   ├── mdsys.sqr      # Kernel binary
│   │   └── pcname.txt     # PC name
│   ├── bin/               # Future system binaries
│   ├── Modules/           # Future kernel modules
│   └── usr/               # User directories
└── Users/                 # User home directories
```

## Code Dependencies

### Dependency Graph

```
Applications/Games
        ↓
    Syscalls
        ↓
   Kernel Core
        ↓
  Memory Manager ←→ Process Manager
        ↓                 ↓
   File Systems      Scheduler
        ↓                 ↓
     Drivers        Context Switch
        ↓                 ↓
    Hardware         Interrupts
```

## Next Steps

- [Coding Standards](Coding-Standards.md) - Style guide
- [Building ModuOS](Building-ModuOS.md) - Build process
- [System Architecture](System-Architecture.md) - Design overview