# Codebase Structure
**Analysis Date:** 2026-01-14
## Directory Layout
```
business-design-mcp/
├── src/ # TypeScript source code
│ ├── index.ts # MCP server entry point
│ ├── schemas/ # Zod validation schemas
│ ├── tools/ # Business logic by framework
│ ├── storage/ # File persistence layer
│ ├── openai/ # OpenAI integration
│ └── test/ # Test setup
├── dist/ # Compiled JavaScript (generated)
├── .github/ # GitHub workflows
│ └── workflows/
│ └── ci.yml # CI pipeline
├── package.json # Project manifest
├── tsconfig.json # TypeScript config
├── vitest.config.ts # Test config
├── README.md # User documentation
└── CLAUDE.md # Development guidelines
```
## Directory Purposes
**src/**
- Purpose: All TypeScript source code
- Contains: Business logic, schemas, storage, integrations
- Key files: `index.ts` (entry point)
- Subdirectories: `tools/`, `schemas/`, `storage/`, `openai/`, `test/`
**src/tools/**
- Purpose: Business logic by framework type
- Contains: CRUD functions and Zod schemas for each tool
- Key files: `project.ts`, `canvas.ts`, `lean.ts`, `research.ts`
- Subdirectories: None (flat structure)
**src/schemas/**
- Purpose: Zod validation schemas and TypeScript types
- Contains: Entity schemas, base types, citation schemas
- Key files: `index.ts` (all schemas), `citations.ts` (research metadata)
- Subdirectories: None
**src/storage/**
- Purpose: File-based persistence layer
- Contains: CRUD operations for projects and entities
- Key files: `index.ts`
- Subdirectories: None
**src/openai/**
- Purpose: OpenAI Deep Research integration
- Contains: API client, prompt templates, response parser
- Key files: `client.ts`, `prompts.ts`, `parser.ts`
- Subdirectories: None
**src/test/**
- Purpose: Test configuration and setup
- Contains: Global test setup with temp directory management
- Key files: `setup.ts`
- Subdirectories: None
## Key File Locations
**Entry Points:**
- `src/index.ts` - MCP server entry, tool registration
**Configuration:**
- `tsconfig.json` - TypeScript configuration
- `vitest.config.ts` - Test runner configuration
- `package.json` - Dependencies, scripts, bin entry
**Core Logic:**
- `src/tools/project.ts` - Project CRUD operations
- `src/tools/canvas.ts` - Business Model Canvas
- `src/tools/research.ts` - Deep Research integration
- `src/storage/index.ts` - File persistence
**Testing:**
- `src/tools/*.test.ts` - Test files co-located with source
- `src/test/setup.ts` - Global test setup
**Documentation:**
- `README.md` - Installation and usage
- `CLAUDE.md` - Development guidelines
## Naming Conventions
**Files:**
- kebab-case for multi-word: `value-prop.ts`, `market.ts`
- *.test.ts for test files: `canvas.test.ts`, `project.test.ts`
- index.ts for barrel exports: `src/tools/index.ts`, `src/schemas/index.ts`
**Directories:**
- kebab-case: `src/tools/`, `src/openai/`
- Plural for collections: `tools/`, `schemas/`
**Special Patterns:**
- Tool files export schema + function pairs: `createXSchema` + `createX()`
- Test files parallel source files: `canvas.ts` → `canvas.test.ts`
## Where to Add New Code
**New Framework/Canvas Type:**
- Primary code: `src/tools/{name}.ts`
- Schema: Add to `src/schemas/index.ts`
- Tests: `src/tools/{name}.test.ts`
- Registration: Add to `src/index.ts`
- Re-export: Add to `src/tools/index.ts`
**New Storage Operation:**
- Implementation: `src/storage/index.ts`
- Types: `src/schemas/index.ts`
- Tests: `src/storage/storage.test.ts`
**New External Integration:**
- Client: `src/{service}/client.ts`
- Types: `src/{service}/types.ts`
- Tests: `src/{service}/*.test.ts`
**New Tool:**
- Implementation: `src/tools/{name}.ts`
- Schema: In same file as function
- Tests: `src/tools/{name}.test.ts`
- Registration: `src/index.ts`
## Special Directories
**dist/**
- Purpose: Compiled JavaScript output
- Source: Generated by `npm run build`
- Committed: No (in .gitignore)
**~/.business-design/** (runtime)
- Purpose: Data storage directory
- Source: Created at runtime by storage layer
- Contains: `projects/*.json`, `entities/*.json`
- Override: `BUSINESS_DESIGN_DATA_DIR` environment variable
---
*Structure analysis: 2026-01-14*
*Update when directory structure changes*
