From b20a77c9a5af98daebb55dd081fc3341e1997aa7 Mon Sep 17 00:00:00 2001
From: Cutieguwu <owen.brooks77@gmail.com>
Date: Thu, 30 Apr 2026 08:46:53 -0400
Subject: [PATCH] Update README.md

---
 README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 139 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1de7495..4e2b283 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,11 @@ from the command line with sanity.
 It takes inspiration from Cargo, and essentially serves as a sanity-preserving
 wrapper for `javac` and `java`.
 
+Because of the Rust-originating concepts, Raven *is opinionated*. If you have a
+major problem with Rust, look away. If you genuinely intend on using Raven,
+probably still look away. This likely won't enter any form of mainstream or
+active long-term support.
+
 ## Installing
 
 Installing with `cargo`:
@@ -22,7 +27,7 @@ worked out over time.
 
 `raven` is only tested under linux. NT and Darwin support is **not** guaranteed.
 
-WSL *may* affect the behaviour of raven. Quirks to be worked out.
+WSL *may* affect the behaviour of Raven. Quirks to be worked out.
 
 ## Getting Started
 
@@ -61,3 +66,136 @@ Options:
     will be implemented should there arise a need.
 - [ ] Wrap errors properly, instead of hap-hazardly using `anyhow`
 - [ ] Maybe proper logging?
+
+## Project Structure
+
+It helps if you're starting from an understanding of a Cargo Workspace.
+
+- **Workspace:** The top level of a project. A workspace contains a series of
+  *packages*.
+- **Package:** An individual library or binary which possesses its own
+  `Nest.toml` or `pom.xml`. This should be equivalent to Maven's concept of a
+  module.
+- **Module:** Any organization of classes and modules which don't possess a
+  `Nest.toml` or `pom.xml`.
+
+If you're unfamiliar with a cargo workspace manifest,  
+An example workspace Nest:
+
+```toml
+[workspace]
+default_package = "app"
+members = [
+    "app",
+    "cli",
+    "core",
+    "installer",
+    "io",
+]
+
+[meta]
+name = "myProject"
+version = "0.1.0"
+
+[dependencies]
+cli = { path = "cli" }
+core = { path = "core" }
+io = { path = "io" }
+```
+
+### Inheritance
+
+Again, this takes from cargo's functionality.
+
+To inherit from the workspace Nest (given the workspace example above):
+
+```toml
+[package]
+entry_point = "Main.java"
+
+[meta]
+name = "app"
+version = "0.1.0"
+
+[dependnencies]
+cli.workspace = true
+io.workspace = true
+```
+
+### Reverse Domain Name Notation
+
+Raven prefers this be trashed, burned, and ground into the earth with your boot.
+
+It is possible to work around this with workspace members and default entry
+points.
+
+Raven feels little need to respect Java's standards.
+
+### Sub-modules
+
+Given the structure:
+
+`WORKSPACE/packageA/packageB`
+
+If you want to have subpackages like maven permits (via submodules), it is
+technically possible by listing the submodule like so in the workspace members:
+
+```toml
+[workspace]
+members = [
+    "packageA",
+    "packageA/packageB",
+]
+
+[dependencies]
+packageA = { path = "packageA" }
+
+[dependencies.packageA]
+path = "packageA"
+dependencies = { packageB = "packageA/packageB" }
+```
+
+Obviously, this is a total disaster, and is considered bad practise under Raven.
+
+The project should be restructured to either:
+
+1. Have all packages immediately within the workspace (remove all nesting), or
+2. Move the complex package with subpackages out of tree into its own workspace
+    and add it as a dependency with a relative path in the workspace Nest. The
+    reason being, that packageA is so complex that it should be maintained as
+    its own thing, and is realistically a fairly universal library.
+
+#### For Option 1
+
+Example workspace Nest:
+
+```toml
+[workspace]
+members = [
+    "packageA",
+    "packageB",
+]
+
+[dependencies]
+packageA = { path = "packageA" }
+packageB = { path = "packageB" }
+```
+
+#### For Option 2
+
+Example workspace Nest:
+
+```toml
+[dependencies]
+packageA = { path = "external/packageA" }
+```
+
+Where packageA's workspace Nest:
+
+```toml
+[workspace]
+members = [
+    "core",
+    "packageB"
+]
+```