diff --git a/README.md b/README.md
index ec04a65..01410f9 100644
--- a/README.md
+++ b/README.md
@@ -35,12 +35,40 @@ The system consists of two main components:
 
 ```
 clubber/
-├── openspec/           # Specification-driven development
-│   ├── project.md      # Project conventions and context
-│   ├── specs/          # Current specifications
-│   └── changes/        # Change proposals
-├── CLAUDE.md           # AI assistant instructions
-└── README.md           # This file
+├── src/                    # Application source code
+│   ├── models/             # SQLAlchemy database models
+│   ├── resolvers/          # GraphQL resolvers (queries and mutations)
+│   ├── schemas/            # GraphQL schema definitions
+│   ├── config.py           # Application configuration
+│   ├── database.py         # Database setup and session management
+│   ├── main.py             # FastAPI application entry point
+│   ├── mcp_server.py       # MCP server implementation
+│   └── validation.py       # Input validation logic
+├── tests/                  # Test suite
+│   ├── unit/               # Unit tests (validation logic)
+│   ├── integration/        # Integration tests (database, resolvers)
+│   ├── e2e/                # End-to-end tests (API flows)
+│   ├── mcp/                # MCP server tests
+│   └── conftest.py         # Shared test fixtures
+├── migrations/             # Alembic database migrations
+│   └── versions/           # Migration version files
+├── scripts/                # Utility scripts
+│   └── seed.py             # Database seeding script
+├── openspec/               # Specification-driven development
+│   ├── specs/              # Current specifications
+│   │   ├── database-layer/
+│   │   ├── graphql-api/
+│   │   ├── mcp-integration/
+│   │   ├── member-crud/
+│   │   ├── project-documentation/
+│   │   └── project-setup/
+│   └── changes/            # Change proposals
+│       └── archive/        # Archived completed changes
+├── pyproject.toml          # Project dependencies and configuration
+├── alembic.ini             # Alembic migration configuration
+├── uv.lock                 # Locked dependency versions
+├── CLAUDE.md               # AI assistant instructions
+└── README.md               # This file
 ```
 
 ## Getting Started