mattermost/.planning/codebase/STRUCTURE.md

# Codebase Structure

**Analysis Date:** 2026-01-13

## Directory Layout

```
mattermost/
├── server/                          # Go backend (HTTP + business logic)
│   ├── cmd/                         # CLI entry points
│   ├── channels/                    # Core messaging domain
│   ├── platform/                    # Shared platform services
│   ├── public/                      # Public API and models
│   ├── einterfaces/                 # Enterprise plugin interfaces
│   ├── enterprise/                  # Enterprise features
│   ├── config/                      # Configuration management
│   └── i18n/                        # Internationalization
│
├── webapp/                          # React/TypeScript frontend
│   ├── channels/                    # Main web application
│   ├── platform/                    # Shared libraries
│   └── scripts/                     # Build scripts
│
├── api/                             # OpenAPI specification
│   ├── v4/                          # REST API v4 docs
│   └── playbooks/                   # Playbooks API docs
│
├── e2e-tests/                       # End-to-end tests
│   ├── playwright/                  # Playwright tests
│   └── cypress/                     # Cypress tests
│
├── tools/                           # Development tools
└── .github/                         # GitHub Actions CI/CD
```

## Directory Purposes

**server/cmd/**
- Purpose: CLI entry points and command definitions
- Contains: Main executables and command handlers
- Key files: `mattermost/main.go`, `mmctl/mmctl.go`
- Subdirectories:
  - `mattermost/` - Main server binary
  - `mattermost/commands/` - CLI commands (server, db, jobs)
  - `mmctl/` - Admin CLI tool

**server/channels/**
- Purpose: Core channels/messaging domain (~1,039 Go files)
- Contains: Business logic, API, store, jobs
- Key files: Entry points in `app/server.go`, `app/app.go`
- Subdirectories:
  - `api4/` - REST API v4 endpoints (151 files)
  - `app/` - Business logic layer (247 files)
  - `store/` - Data access abstraction
  - `store/sqlstore/` - SQL implementation (134 files)
  - `web/` - Web handlers (HTML, auth, static)
  - `wsapi/` - WebSocket API
  - `jobs/` - Background jobs (47 types)
  - `audit/` - Audit logging

**server/platform/services/**
- Purpose: Shared infrastructure services
- Contains: Cross-cutting concerns used by channels
- Key files: Service implementations
- Subdirectories:
  - `searchengine/` - Search/indexing
  - `cache/` - Caching service
  - `telemetry/` - Analytics and metrics
  - `imageproxy/` - Image proxy
  - `marketplace/` - Plugin marketplace
  - `remotecluster/` - Remote cluster support
  - `sharedchannel/` - Shared channels

**server/public/model/**
- Purpose: Public API models and types
- Contains: Data structures, validation, constants
- Key files: `user.go`, `channel.go`, `post.go`, `config.go`

**webapp/channels/**
- Purpose: Main web application (~3,545 TS/JS files)
- Contains: React components, Redux, utilities
- Key files: `src/entry.tsx`, `src/root.tsx`
- Subdirectories:
  - `src/components/` - React components (341 dirs)
  - `src/actions/` - Redux action creators (47 files)
  - `src/reducers/` - Redux reducers
  - `src/selectors/` - Redux selectors (34 files)
  - `src/client/` - API client wrapper
  - `src/utils/` - Utilities (118 modules)
  - `src/hooks/` - Custom React hooks
  - `src/types/` - TypeScript definitions
  - `src/i18n/` - Internationalization (70 dirs)
  - `src/sass/` - SCSS styles

**webapp/platform/**
- Purpose: Shared libraries (npm workspaces)
- Contains: Reusable packages across apps
- Subdirectories:
  - `client/` - Reusable API client SDK
  - `components/` - Shared UI components
  - `types/` - Shared TypeScript types
  - `mattermost-redux/` - Redux utilities
  - `eslint-plugin/` - Custom ESLint rules

## Key File Locations

**Entry Points:**
- `server/cmd/mattermost/main.go` - Server CLI entry
- `server/cmd/mattermost/commands/server.go` - HTTP server startup
- `server/cmd/mmctl/mmctl.go` - Admin CLI entry
- `webapp/channels/src/entry.tsx` - React app initialization
- `webapp/channels/src/root.html` - HTML template

**Configuration:**
- `server/config/` - Server configuration management
- `server/public/model/config.go` - Config structure (5,401 lines)
- `webapp/channels/webpack.config.js` - Webpack bundler
- `webapp/channels/tsconfig.json` - TypeScript config
- `.editorconfig` - Editor settings

**Core Logic:**
- `server/channels/app/` - Business logic (user, channel, post, team)
- `server/channels/store/sqlstore/` - Database operations
- `webapp/channels/src/actions/` - Redux async operations
- `webapp/platform/client/src/client4.ts` - API client (4,865 lines)

**Testing:**
- `server/channels/**/*_test.go` - Go unit/integration tests
- `webapp/channels/src/**/*.test.tsx` - Jest component tests
- `e2e-tests/playwright/specs/` - Playwright E2E tests
- `e2e-tests/cypress/` - Cypress E2E tests

**Documentation:**
- `README.md` - Project overview
- `CONTRIBUTING.md` - Contribution guide
- `webapp/STYLE_GUIDE.md` - Frontend coding standards
- `e2e-tests/playwright/CLAUDE.md` - E2E testing guidance
- `api/v4/source/` - OpenAPI specifications

## Naming Conventions

**Files:**
- Go: `snake_case.go` (e.g., `channel_store.go`, `user_actions.go`)
- TypeScript components: Directory per component (e.g., `about_build_modal/`)
- TypeScript utilities: `snake_case.ts` (e.g., `post_utils.ts`)
- Tests: `*_test.go` (Go), `*.test.ts(x)` (TypeScript)
- Hooks: `use*.ts` (e.g., `useBurnOnReadTimer.ts`)

**Directories:**
- `snake_case` for feature directories
- Plural for collections: `components/`, `actions/`, `services/`

**Special Patterns:**
- `*_store.go` - Store implementations
- `*_test.go` - Go tests in same directory
- `index.ts(x)` - Directory barrel exports
- `__tests__/` - Test directories (some areas)

## Where to Add New Code

**New Feature (Backend):**
- Primary code: `server/channels/app/{feature}.go`
- API endpoints: `server/channels/api4/{feature}.go`
- Store interface: `server/channels/store/store.go`
- SQL implementation: `server/channels/store/sqlstore/{feature}_store.go`
- Tests: `*_test.go` alongside source

**New Feature (Frontend):**
- Components: `webapp/channels/src/components/{feature}/`
- Actions: `webapp/channels/src/actions/{feature}_actions.ts`
- Reducers: `webapp/channels/src/reducers/entities/{feature}.ts`
- Selectors: `webapp/channels/src/selectors/{feature}.ts`
- Tests: `*.test.tsx` alongside source

**New API Endpoint:**
- Handler: `server/channels/api4/{resource}.go`
- Route: Register in `server/channels/api4/api.go`
- Client method: `webapp/platform/client/src/client4.ts`
- Types: `server/public/model/{resource}.go`, `webapp/platform/types/src/`

**Background Job:**
- Implementation: `server/channels/jobs/{job_name}/`
- Registration: `server/channels/app/server.go`

**Shared UI Component:**
- Implementation: `webapp/platform/components/src/`
- Export: Update barrel file

## Special Directories

**server/channels/store/sqlstore/**
- Purpose: SQL database implementations
- Source: Hand-written, matches store interfaces
- Committed: Yes

**server/channels/store/retrylayer/**
- Purpose: Auto-generated retry wrapper (17,617 lines)
- Source: Generated from store interfaces
- Committed: Yes (regenerate when interfaces change)

**server/channels/store/timerlayer/**
- Purpose: Auto-generated timing instrumentation (14,047 lines)
- Source: Generated from store interfaces
- Committed: Yes (regenerate when interfaces change)

**server/enterprise/**
- Purpose: Enterprise-only features
- Source: Separate licensing
- Committed: Yes (requires enterprise license to run)

**webapp/channels/build/**
- Purpose: Webpack build output
- Source: Generated during build
- Committed: No (in .gitignore)

**node_modules/**
- Purpose: npm dependencies
- Source: Installed via `npm install`
- Committed: No (in .gitignore)

---

*Structure analysis: 2026-01-13*
*Update when directory structure changes*