diff --git a/README.md b/README.md
index 8679ad1b2ca5cf32408d0ff166b12d98271265b5..f34a693c7f12727007d21d819687d5fa315af5d9 100644
--- a/README.md
+++ b/README.md
@@ -107,15 +107,26 @@ There's `flash/monitor` targets, too (but no openocd/gdb...). To pick what port
 
 ## How to modify
 
+### Structure
+
+```
+main/               - main module, starts micropython on core1 and continues
+                      executing components/badge23/.
+usermodule/         - `hardware`, `synth`, ... C modules exposed to micropython.
+components/badge23/ - main ESP-IDF `app_main`, runs on core 0 after micropython
+                      gets started on core1.
+components/gc9a01/  - low-level LCD driver.
+```
+
 ### General info
 
-Global + micropython entry point: app\_main() in micropython/ports/esp32/main.c (includes badge23/espan.h).
+Global + micropython entry point: `app_main()` in `micropython/ports/esp32/main.c`, compiled into `main/` component.
 
-C entry point, called by^: os\_app\_main() in badge23/espan.c
+C entry point, called by^: `os_app_main()` in components/badge23/espan.c
 
-Register new c files for compilation: add to set(BADGE23\_SOURCE) in main/CMakelists.txt
+Register new C files for compilation: add to components/badge23/CMakelists.txt
 
-Change output volume in the set\_global\_vol\_dB(int8\_t) call; -90 for mute
+Change output volume in the `set_global_vol_dB(int8_t)` call; -90 for mute
 
 ### Debugging
 
diff --git a/components/badge23/README.md b/components/badge23/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..990eb72c4b17f431b7bdc8f4255d07ea8aefa3ec
--- /dev/null
+++ b/components/badge23/README.md
@@ -0,0 +1,6 @@
+badge23/espan
+===
+
+Transitional component containing all custom C code for badge23, including drivers for peripherals and 'espan' application leftovers.
+
+This will be likely split up into sub-components.
diff --git a/main/README.md b/main/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..8deec1e0bde309b37773ef94e9684f7d2cbb23aa
--- /dev/null
+++ b/main/README.md
@@ -0,0 +1,6 @@
+micropython shim module
+===
+
+This is the 'main' module from ESP-IDF, and its job is to just start
+micropython and continue executing `app_main` from
+`components/badge23/espan.c`.
diff --git a/usermodule/README.md b/usermodule/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ac5f07b6722a4d54e48c85ef1639e370686d578f
--- /dev/null
+++ b/usermodule/README.md
@@ -0,0 +1,3 @@
+micropython C modules
+===
+
diff --git a/usermodule/micropython.cmake b/usermodule/micropython.cmake
index fbc5ed9b56ed0a2a667482ee6a62139568b8fe86..d647bb687cbbf8476d7b54b94bad12a65477a656 100644
--- a/usermodule/micropython.cmake
+++ b/usermodule/micropython.cmake
@@ -1,3 +1,7 @@
+# If you want to add dependencies on other ESP-IDF modules, add them to
+# IDF_COMPONENTS in main/CMakeLists, as main/ is the component that the
+# usermodules are actually part of.
+
 add_library(usermod_badge23 INTERFACE)
 
 target_sources(usermod_badge23 INTERFACE