diff --git a/README.md b/README.md
index 6a5bc5a..cb1acd2 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,22 @@
 # spec-examples
-Example spec files to create service in Omnistrate
+
+Example specification and compose files for creating services in Omnistrate.
+
+## Repository Structure
+
+This repository is organized into the following directories:
+
+### `/spec`
+Contains Omnistrate specification examples:
+- **`/spec/byoa`** - Examples for BYOA (Bring Your Own Account) deployments
+- **`/spec/hosted`** - Examples for hosted deployments
+
+### `/compose`
+Contains Docker Compose examples:
+- **`/compose/byoa`** - Docker Compose examples for BYOA deployments  
+- **`/compose/hosted`** - Docker Compose examples for hosted deployments
+
+## Deployment Types
+
+- **BYOA (Bring Your Own Account)**: Customers deploy services in their own cloud accounts while leveraging Omnistrate's management capabilities
+- **Hosted**: Services are managed and hosted by the service provider using Omnistrate's infrastructure
diff --git a/compose/byoa/README.md b/compose/byoa/README.md
new file mode 100644
index 0000000..82f6830
--- /dev/null
+++ b/compose/byoa/README.md
@@ -0,0 +1,5 @@
+# Compose - BYOA (Bring Your Own Account)
+
+This directory contains Docker Compose examples for BYOA (Bring Your Own Account) deployments.
+
+These examples show how to structure and configure Docker Compose files for services that will be deployed in customer-owned cloud accounts.
\ No newline at end of file
diff --git a/compose/hosted/README.md b/compose/hosted/README.md
new file mode 100644
index 0000000..599a679
--- /dev/null
+++ b/compose/hosted/README.md
@@ -0,0 +1,5 @@
+# Compose - Hosted
+
+This directory contains Docker Compose examples for hosted deployments.
+
+These examples show how to structure and configure Docker Compose files for services that will be hosted and managed by the service provider.
\ No newline at end of file
diff --git a/spec/byoa/README.md b/spec/byoa/README.md
new file mode 100644
index 0000000..49bf774
--- /dev/null
+++ b/spec/byoa/README.md
@@ -0,0 +1,5 @@
+# Spec - BYOA (Bring Your Own Account)
+
+This directory contains Omnistrate specification examples for BYOA (Bring Your Own Account) deployments.
+
+BYOA deployments allow customers to deploy services in their own cloud accounts while still leveraging Omnistrate's management capabilities.
\ No newline at end of file
diff --git a/spec/hosted/README.md b/spec/hosted/README.md
new file mode 100644
index 0000000..fb3e512
--- /dev/null
+++ b/spec/hosted/README.md
@@ -0,0 +1,5 @@
+# Spec - Hosted
+
+This directory contains Omnistrate specification examples for hosted deployments.
+
+Hosted deployments are managed and hosted by the service provider using Omnistrate's infrastructure.
\ No newline at end of file