# Codebase Structure
**Analysis Date:** 2026-01-16
## Directory Layout
```
swift-mcp/
├── src/ # TypeScript source code
│ ├── index.ts # MCP server entry point
│ ├── cli/ # CLI commands
│ ├── config/ # Configuration and constants
│ ├── sources/ # Content source implementations
│ │ ├── free/ # Free sources (RSS-based)
│ │ └── premium/ # Premium sources (Patreon, YouTube)
│ ├── tools/ # Utility tools
│ └── utils/ # Shared utilities
├── build/ # Compiled JavaScript output
├── .github/ # GitHub Actions workflows
├── .planning/ # Project planning documents
├── package.json # Project manifest
├── tsconfig.json # TypeScript configuration
└── eslint.config.js # ESLint configuration
```
## Directory Purposes
**src/**
- Purpose: All TypeScript source code
- Contains: Entry point, modules organized by function
- Key files: `index.ts` (MCP server main)
- Subdirectories: cli, config, sources, tools, utils
**src/cli/**
- Purpose: Command-line interface tools
- Contains: Setup wizard, auth management, source management
- Key files:
- `setup.ts` - Patreon OAuth configuration wizard
- `auth.ts` - Reset authentication data
- `source-manager.ts` - Enable/disable content sources
**src/config/**
- Purpose: Configuration files and registries
- Contains: Source definitions, creator mappings, keyword constants
- Key files:
- `sources.ts` - SourceManager class and source registry
- `creators.ts` - Patreon creator ID to YouTube channel mappings
- `swift-keywords.ts` - Shared topic keywords and quality signals
**src/sources/free/**
- Purpose: Free content sources (no auth required)
- Contains: RSS-based source implementations
- Key files:
- `rssPatternSource.ts` - Abstract base class for RSS sources
- `sundell.ts` - Swift by Sundell source
- `vanderlee.ts` - Antoine van der Lee source (with full article fetch)
- `*.test.ts` - Co-located test files
**src/sources/premium/**
- Purpose: Premium content sources (auth required)
- Contains: Patreon integration, YouTube integration
- Key files:
- `patreon.ts` - Main Patreon source implementation
- `patreon-oauth.ts` - OAuth 2.0 token management
- `patreon-dl.ts` - Downloaded content scanning
- `patreon-zip.ts` - ZIP file extraction for attachments
- `patreon-fetch.ts` - API fetching utilities
- `youtube.ts` - YouTube Data API integration
**src/tools/**
- Purpose: One-off utility tools
- Contains: Browser automation for auth
- Key files:
- `extract-cookie.ts` - Playwright-based Patreon session extraction
**src/utils/**
- Purpose: Shared utilities and helpers
- Contains: Caching, search, analysis, path resolution
- Key files:
- `cache.ts` - FileCache class with memory + file layers
- `search.ts` - SearchIndex with MiniSearch integration
- `swift-analysis.ts` - Topic detection, code analysis, relevance scoring
- `paths.ts` - Cross-platform config directory resolution
**build/**
- Purpose: Compiled JavaScript output
- Contains: ES2022 JavaScript files mirroring src/ structure
- Source: Generated by `tsc` from src/
- Committed: No (in .gitignore)
**.github/workflows/**
- Purpose: CI/CD pipeline configuration
- Contains: GitHub Actions workflow files
- Key files: `ci.yml` - Lint, build, test on push/PR
## Key File Locations
**Entry Points:**
- `src/index.ts` - MCP server main entry
- `src/cli/setup.ts` - CLI setup command
- `src/cli/auth.ts` - CLI auth command
- `src/cli/source-manager.ts` - CLI source command
**Configuration:**
- `tsconfig.json` - TypeScript compiler options
- `eslint.config.js` - ESLint rules (flat config)
- `package.json` - Dependencies, scripts, bin config
- `.env.example` - Environment variable template
**Core Logic:**
- `src/config/sources.ts` - Source orchestration
- `src/sources/free/rssPatternSource.ts` - RSS processing base
- `src/sources/premium/patreon.ts` - Patreon integration
- `src/utils/swift-analysis.ts` - Content analysis pipeline
**Testing:**
- `src/sources/free/rssPatternSource.test.ts` - Base source tests
- `src/sources/free/sundell.test.ts` - Sundell source tests
- `src/sources/free/vanderlee.test.ts` - VanderLee source tests
**Documentation:**
- `README.md` - User-facing installation and usage
- `CLAUDE.md` - Instructions for Claude Code
- `.planning/` - Planning documents and codebase map
## Naming Conventions
**Files:**
- `camelCase.ts` - Standard modules (`rssPatternSource.ts`, `swiftAnalysis.ts`)
- `kebab-case.ts` - Multi-word utilities (`source-manager.ts`, `patreon-oauth.ts`)
- `*.test.ts` - Test files co-located with source
- `UPPERCASE.md` - Important documentation files
**Directories:**
- lowercase for all directories
- Plural for collections: `sources/`, `utils/`, `tools/`
- Singular for namespaces: `config/`, `cli/`
**Special Patterns:**
- `index.ts` - Entry point, no barrel exports
- No `__tests__/` directory (tests co-located)
## Where to Add New Code
**New Content Source:**
- Free source: `src/sources/free/{name}.ts` extending `RssPatternSource`
- Premium source: `src/sources/premium/{name}.ts`
- Tests: `src/sources/{free|premium}/{name}.test.ts`
- Register in: `src/config/sources.ts`
**New CLI Command:**
- Implementation: `src/cli/{command}.ts`
- Add script to `package.json`
- Update README with usage
**New Utility:**
- Implementation: `src/utils/{name}.ts`
- Pure functions, minimal dependencies
- Export named functions
**New Tool Handler:**
- Add tool definition in `src/index.ts` (CORE_TOOLS or PATREON_TOOLS)
- Add handler case in `server.setRequestHandler(CallToolRequestSchema, ...)`
## Special Directories
**~/.swift-mcp/ (User Home):**
- Purpose: Runtime configuration and cache
- Contents:
- `config.json` - Source enable/disable state
- `cache/` - Cached RSS feeds and articles
- `patreon-content/` - Downloaded Patreon posts
- Committed: No (user's home directory)
**.patreon-profile/ (Project Root):**
- Purpose: Persistent Playwright browser profile
- Source: Created by extract-cookie.ts
- Committed: No (in .gitignore)
---
*Structure analysis: 2026-01-16*
*Update when directory structure changes*
