docs: expansion to help understand anatomy and code api in user here

nix/docs/README.md

@@ -11,6 +11,8 @@ learn how to play with `postgres` in the [build guide](./build-postgres.md).
 ## Development
 
 - **[Nix tree structure](./nix-directory-structure.md)** - Overview of the Nix directory structure
+- **[Flake-Parts Architecture](./flake-parts-architecture.md)** - Deep dive into the flake-parts module system
+- **[Flake-Parts and nixpkgs lib](./flake-parts-nixpkgs-lib.md)** - How flake-parts uses nixpkgs lib foundations
 - **[Development Workflow](./development-workflow.md)** - Complete development and testing workflow
 - **[Build PostgreSQL](./build-postgres.md)** - Building PostgreSQL from source
 - **[Receipt Files](./receipt-files.md)** - Understanding build receipts

nix/docs/adding-new-package.md

@@ -1,5 +1,10 @@
 # Adding a new extension package
 
+!!! tip "Understanding the Module System"
+    To better understand how packages are organized and how `ourExtensions` works with flake-parts, see:
+
+    - **[Flake-Parts Architecture](./flake-parts-architecture.md)** - Module structure overview
+    - **[Flake-Parts and nixpkgs lib](./flake-parts-nixpkgs-lib.md)** - Extension composition patterns
 
 ## Pre-packaging steps
 1. Make sure you have nix installed [Nix installer](https://github.com/DeterminateSystems/nix-installer)