diff --git a/src/app.rs b/src/app.rs
index 71194a8..4a461c1 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -1,3 +1,9 @@
+/*
+ * Contains the core DungeonApp struct and its eframe::App implementation.
+ * This file manages the application lifecycle, main state, undo/redo stacks,
+ * and high-level level management (generation, deletion, and refreshing).
+ */
+
 use std::collections::HashSet;
 use std::sync::mpsc;
 use std::thread;
diff --git a/src/exporter.rs b/src/exporter.rs
index 2333bb9..82c837a 100644
--- a/src/exporter.rs
+++ b/src/exporter.rs
@@ -1,3 +1,10 @@
+/*
+ * Image and vector export module.
+ * Handles building SVG representations of dungeon levels and
+ * exporting them to various formats (PNG, JPEG, WebP, SVG)
+ * via a background thread to maintain UI responsiveness.
+ */
+
 use std::collections::HashSet;
 use std::fmt::Write as _;
 use std::path::PathBuf;
diff --git a/src/interact.rs b/src/interact.rs
index 3295ea8..a0f2757 100644
--- a/src/interact.rs
+++ b/src/interact.rs
@@ -1,3 +1,12 @@
+/*
+ * Manages user interaction and grid-based logic for the dungeon canvas.
+ * Includes logic for:
+ *   - Dragging and moving rooms, corridors, markers, and text.
+ *   - Resizing rooms, text, and staircases.
+ *   - Handling "Add" tool operations (placing new rooms, doors, etc.).
+ *   - Hit testing and hover detection for all dungeon elements.
+ */
+
 use crate::app::{DungeonApp, ManualDoorKind};
 use crate::layout::{
     self, blocked_room_cells, corridor_cells, rects_overlap, room_index_at_cell, rooms_overlap,
diff --git a/src/layout/generation.rs b/src/layout/generation.rs
index d434410..501fb22 100644
--- a/src/layout/generation.rs
+++ b/src/layout/generation.rs
@@ -1,3 +1,10 @@
+/*
+ * High-level procedural generation algorithms.
+ * Contains the logic for building room connection graphs,
+ * placing packed rooms, and populating random markers, traps,
+ * monsters, and staircase transitions between levels.
+ */
+
 use super::types::{
     AreaMarker, Corridor, Door, DoorSettings, DungeonLayout, Room, Staircase, Window,
     WindowSettings, WindowSide,
diff --git a/src/layout/mod.rs b/src/layout/mod.rs
index 704a3ed..20a960b 100644
--- a/src/layout/mod.rs
+++ b/src/layout/mod.rs
@@ -1,4 +1,10 @@
 pub mod generation;
+/*
+ * Public entry point for the layout module.
+ * Exports types, utilities, and generation algorithms used to build
+ * the dungeon structure.
+ */
+
 pub mod types;
 pub mod utils;
 
diff --git a/src/layout/types.rs b/src/layout/types.rs
index 266ec85..8cc00e8 100644
--- a/src/layout/types.rs
+++ b/src/layout/types.rs
@@ -1,3 +1,9 @@
+/*
+ * Core data structures for the dungeon layout.
+ * Defines structs for Rooms, Corridors, Doors, Windows, Stairs,
+ * TextLabels, and the master DungeonLayout container.
+ */
+
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/src/layout/utils.rs b/src/layout/utils.rs
index fc8fc74..5f90265 100644
--- a/src/layout/utils.rs
+++ b/src/layout/utils.rs
@@ -1,3 +1,9 @@
+/*
+ * Geometric utilities and low-level layout helpers.
+ * Provides logic for Manhattan distance, room overlap testing,
+ * BFS-based shortest pathfinding, and custom deterministic RNG.
+ */
+
 use super::types::{DungeonLayout, Room};
 use std::collections::{HashSet, VecDeque};
 
diff --git a/src/main.rs b/src/main.rs
index 0e7a68a..92d5b0c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,3 +1,9 @@
+/*
+ * Entry point for the Desktop Dungeon Generator.
+ * Handles application initialization, module declarations,
+ * and starts the eframe/egui event loop.
+ */
+
 mod app;
 mod exporter;
 mod interact;
diff --git a/src/rendering.rs b/src/rendering.rs
index 218221e..1a098a7 100644
--- a/src/rendering.rs
+++ b/src/rendering.rs
@@ -1,3 +1,9 @@
+/*
+ * Canvas drawing logic for the dungeon layout.
+ * Provides functions to render rooms, corridors, walls, doors, windows,
+ * and various markers using egui's Painter API.
+ */
+
 use crate::interact::{
     GridGeometry, HoverMarker, MarkerKind, cell_center, cell_rect, door_edges_for,
     door_render_width, marker_rect, normalized_edge, window_render_width,
diff --git a/src/saveandload.rs b/src/saveandload.rs
index b64f90c..c6c7d58 100644
--- a/src/saveandload.rs
+++ b/src/saveandload.rs
@@ -3,6 +3,12 @@ use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::PathBuf;
 
+/*
+ * Persistence logic for dungeon state.
+ * Handles saving and loading the complete dungeon state
+ * (settings and layout data) to and from disk using JSON.
+ */
+
 use crate::layout::DungeonLayout;
 use crate::ui::UiSettings;
 
diff --git a/src/seed.rs b/src/seed.rs
index 8488d67..69ee5f9 100644
--- a/src/seed.rs
+++ b/src/seed.rs
@@ -1,3 +1,9 @@
+/*
+ * Deterministic seed management.
+ * Provides functions to generate random master seeds and
+ * derive sub-seeds for specific procedural generation steps.
+ */
+
 use std::time::{SystemTime, UNIX_EPOCH};
 
 // Generate a random master seed from time and process id.
diff --git a/src/settings.rs b/src/settings.rs
index aedd39d..fc87491 100644
--- a/src/settings.rs
+++ b/src/settings.rs
@@ -1,3 +1,9 @@
+/*
+ * Application-level persistent configuration.
+ * Manages the loading and saving of UiSettings to the system's
+ * local data directory.
+ */
+
 use std::fs;
 use std::io;
 use std::path::PathBuf;
diff --git a/src/ui/mod.rs b/src/ui/mod.rs
index 42b3040..66994cd 100644
--- a/src/ui/mod.rs
+++ b/src/ui/mod.rs
@@ -1,3 +1,8 @@
+/*
+ * The primary UI module. Defines the UiSettings structure and
+ * manages the side panel layout, legend panel, and level selection tabs.
+ * Serves as the entry point for all UI-related rendering.
+ */
 use eframe::egui;
 use serde::{Deserialize, Serialize};
 
diff --git a/src/ui/tabs.rs b/src/ui/tabs.rs
index 3b6410d..1b1bfbc 100644
--- a/src/ui/tabs.rs
+++ b/src/ui/tabs.rs
@@ -1,4 +1,10 @@
 use super::{AddTool, ExportFormat, MaskFormat, SidePanelResult, UiSettings};
+/*
+ * Individual tab rendering logic for the side panel.
+ * Contains functions for drawing the "Generate", "Layout", "Add",
+ * "Start & End", and "Monsters & Traps" control panels.
+ */
+
 use crate::seed;
 use eframe::egui;
 use egui::RichText;
diff --git a/src/ui/widgets.rs b/src/ui/widgets.rs
index d3e1b97..b977ea1 100644
--- a/src/ui/widgets.rs
+++ b/src/ui/widgets.rs
@@ -1,3 +1,9 @@
+/*
+ * Reusable UI components and drawing helpers.
+ * Includes logic for legend entries (standard and colorblind-friendly)
+ *   and custom line styling (dashed, dotted, dash-dot patterns).
+ */
+
 use eframe::egui;
 use egui::{Color32, Stroke};