diff --git a/README.md b/README.md
index 970b2fa..09f3172 100644
--- a/README.md
+++ b/README.md
@@ -43,3 +43,24 @@ pnpm run build:dev
 # Or build all packages in the monorepo (production)
 pnpm run build:prod
 ```
+
+## Repository Structure
+
+```
+editor/
+├── .github/                    # CI workflows, issue templates, Dependabot
+├── .husky/                     # Git hooks (commit-msg, pre-commit)
+├── packages/                   # Monorepo workspace packages
+├── .oxfmtrc.json               # Formatter config (oxfmt)
+├── .oxlintrc.json              # Linter config (oxlint)
+├── .syncpackrc.json            # Monorepo package version consistency
+├── netlify.toml                # Netlify configuration for Storybook preview deployment
+├── pnpm-workspace.yaml         # pnpm workspace definition
+└── tsconfig.base.json          # Shared TypeScript config
+```
+
+### Key Packages
+
+#### packages/serverless-workflow-diagram-editor/
+
+The visual diagram editor for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification/). Built with React Flow for interactive diagram rendering and includes Storybook for component development.
diff --git a/packages/serverless-workflow-diagram-editor/README.md b/packages/serverless-workflow-diagram-editor/README.md
index 4999117..5120843 100644
--- a/packages/serverless-workflow-diagram-editor/README.md
+++ b/packages/serverless-workflow-diagram-editor/README.md
@@ -1,12 +1,12 @@
 <!--
    Copyright 2021-Present The Serverless Workflow Specification Authors
-  
+
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
-  
+
    http://www.apache.org/licenses/LICENSE-2.0
-  
+
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -16,8 +16,7 @@
 
 # serverless-workflow-diagram-editor
 
-Serverless Workflow Diagram Editor react component / npm package.
----
+Serverless Workflow Diagram Editor React component / npm package
 
 ## Building the Component
 
@@ -39,4 +38,26 @@ pnpm run build:storybook
 
 # Run storybook (test and development / debugging)
 pnpm run start
-```
\ No newline at end of file
+```
+
+## Package Structure
+
+```
+serverless-workflow-diagram-editor/
+├── src/
+│   ├── core/                   # SDK abstraction layer
+│   ├── diagram-editor/         # Main DiagramEditor component
+│   ├── i18n/locales/           # Locale string definitions (en, fr)
+│   ├── react-flow/diagram/     # @xyflow/react diagram rendering
+│   └── store/                  # React Context state management
+├── tests/
+│   ├── core/                   # SDK integration tests
+│   ├── diagram-editor/         # DiagramEditor component tests
+│   ├── react-flow/diagram/     # Diagram rendering tests
+│   ├── store/                  # Context provider tests
+│   └── fixtures/               # Shared test fixtures (workflow YAML/JSON)
+├── stories/                    # Storybook stories and demo components
+├── vitest.config.ts            # Unit test config
+├── tsconfig.json               # TypeScript config
+└── tsconfig.test.json          # TypeScript config for tests
+```