mattermost/.planning/codebase/ARCHITECTURE.md

# Architecture

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

## Pattern Overview

**Overall:** Layered Monolith (Go Backend + React Frontend)

**Key Characteristics:**
- Request-scoped application service pattern (`App` struct per request)
- Clean separation between HTTP handling, business logic, and data access
- Plugin architecture for extensibility
- Real-time WebSocket communication alongside REST API
- Multi-database support (PostgreSQL, MySQL, SQLite)

## Layers

**HTTP/Router Layer:**
- Purpose: Handle incoming HTTP requests, routing, and response formatting
- Contains: Route definitions, middleware, request/response handlers
- Location: `server/channels/api4/` (REST API v4), `server/channels/web/` (web handlers)
- Depends on: Application layer
- Used by: External clients, web browsers

**Application/Business Logic Layer:**
- Purpose: Core domain logic, business rules, and orchestration
- Contains: User management, channel operations, post handling, team management, authentication, plugins
- Location: `server/channels/app/` (~247 Go files)
- Depends on: Store layer, platform services
- Used by: API handlers

**Data Access/Store Layer:**
- Purpose: Database abstraction, caching, search integration
- Contains: Store interfaces, SQL implementations, cache wrappers, retry logic
- Location: `server/channels/store/` (interfaces), `server/channels/store/sqlstore/` (SQL impl)
- Depends on: Database drivers, cache services
- Used by: Application layer

**Platform Services Layer:**
- Purpose: Cross-cutting infrastructure services
- Contains: Search engine, caching, telemetry, image proxy, marketplace integration
- Location: `server/platform/services/`
- Depends on: External services (Redis, Elasticsearch)
- Used by: Application layer, Store layer

**Frontend UI Layer:**
- Purpose: User interface and client-side logic
- Contains: React components, Redux state management, API client
- Location: `webapp/channels/src/`
- Depends on: Backend REST API and WebSocket
- Used by: End users via browser

## Data Flow

**HTTP Request (REST API):**

1. Request → `Server.RootRouter` (Gorilla mux) - `server/channels/app/server.go`
2. Router matches path → `api4.APIHandler` or `web.Handler`
3. `web.Context` created with user session and request data
4. Handler extracts parameters, validates input
5. Handler calls `App` methods (e.g., `a.GetUser()`)
6. `App` delegates to domain-specific logic files
7. Data access via `Store()` interfaces → SQL/Cache layers
8. Response marshalled as JSON and returned to client

**WebSocket Event:**

1. Client connects → `/api/v4/websocket`
2. `Server.WebSocketRouter` handles connection - `server/channels/app/web_hub.go`
3. Events broadcast to relevant users/channels
4. Real-time updates for typing, posts, presence

**Frontend Request Flow:**

1. React component dispatches Redux action - `webapp/channels/src/actions/`
2. Async thunk calls API client method - `webapp/platform/client/src/client4.ts`
3. HTTP request to Go backend
4. Response updates Redux store - `webapp/channels/src/reducers/`
5. Components re-render based on state changes via selectors

**State Management:**
- Backend: Stateless per-request (database is source of truth)
- Frontend: Redux store with persistence (redux-persist)
- Sessions: Database-backed with optional Redis for clustering
- Real-time: WebSocket hub maintains active connections

## Key Abstractions

**App (Application Service):**
- Purpose: Request-scoped service containing business logic
- Examples: `server/channels/app/user.go`, `server/channels/app/channel.go`, `server/channels/app/post.go`
- Pattern: Methods like `(a *App) GetUser()`, `(a *App) CreatePost()`
- Location: `server/channels/app/app.go` - struct definition

**Store (Data Access Interface):**
- Purpose: Abstract database operations from business logic
- Examples: `UserStore`, `ChannelStore`, `PostStore`, `TeamStore`
- Pattern: Interface-based with multiple implementations (SQL, cache, search, retry layers)
- Location: `server/channels/store/store.go` - interface definitions

**Handler (HTTP Handler):**
- Purpose: HTTP request handling with middleware chain
- Examples: `server/channels/api4/user.go`, `server/channels/api4/channel.go`
- Pattern: `func (api *API) getUser(c *Context, w http.ResponseWriter, r *http.Request)`
- Location: `server/channels/api4/handlers.go` - handler utilities

**Job (Background Processing):**
- Purpose: Asynchronous task execution
- Examples: `export_process`, `import_process`, `cleanup_*`, `active_users`
- Pattern: Job struct implementing scheduler interface
- Location: `server/channels/jobs/` (~30+ job types)

**Redux Action/Thunk (Frontend):**
- Purpose: Async operations and state updates
- Examples: `webapp/channels/src/actions/channel_actions.ts`, `user_actions.ts`
- Pattern: Returns `{data: ...}` or `{error: ...}`
- Location: `webapp/channels/src/actions/`

**Selector (Frontend State Query):**
- Purpose: Memoized state queries
- Examples: `webapp/channels/src/selectors/`
- Pattern: `createSelector` for memoization, `makeGet*` factories
- Location: `webapp/channels/src/selectors/`

## Entry Points

**Server Entry:**
- Location: `server/cmd/mattermost/main.go`
- Triggers: `go run ./cmd/mattermost` or compiled binary
- Responsibilities: Initialize CLI, register commands, start server

**Server Command:**
- Location: `server/cmd/mattermost/commands/server.go`
- Triggers: `mattermost server` command
- Responsibilities: Configure and start HTTP server, initialize services

**CLI Tool (mmctl):**
- Location: `server/cmd/mmctl/mmctl.go`
- Triggers: `mmctl <command>` for administration
- Responsibilities: Remote server management, bulk operations

**Frontend Entry:**
- Location: `webapp/channels/src/entry.tsx` (app init), `webapp/channels/src/root.tsx` (webpack root)
- Triggers: Browser page load
- Responsibilities: Initialize React, Redux store, API client, render app

## Error Handling

**Strategy:** Throw/return errors, catch at boundaries, log with context

**Patterns:**
- Backend: Return `*model.AppError` for business errors, Go `error` for system errors
- Custom error type: `model.AppError` with status code, message, details
- Error logging: Structured logs with request context before returning
- Frontend: Redux actions return `{error: ServerError}`, UI displays error messages

**Error Flow:**
1. Store layer returns Go `error` for DB issues
2. App layer converts to `*model.AppError` with business context
3. API handler logs error, returns appropriate HTTP status
4. Client receives structured error response

## Cross-Cutting Concerns

**Logging:**
- Backend: `github.com/mattermost/logr/v2` structured logging - `server/platform/shared/mlog/`
- Frontend: Console logging in development
- Format: JSON structured with request ID, user ID, operation context

**Validation:**
- Backend: Model validation methods (e.g., `model.User.IsValid()`)
- API: Input validation in handlers before calling App methods
- Frontend: Form validation before API calls

**Authentication:**
- Backend: Session-based with JWT tokens - `server/channels/app/authentication.go`
- Middleware: Auth check on protected API routes - `server/channels/api4/api.go`
- Frontend: Token stored in cookies, refreshed automatically

**Authorization:**
- Backend: Permission checks via `app.HasPermissionTo*()` methods
- Roles: System admin, team admin, channel admin, user
- Schemes: Custom permission schemes for teams/channels

**Caching:**
- Local cache layer: `server/channels/store/localcachelayer/`
- Redis (optional): Session cache, cluster pub/sub
- Frontend: Redux store persistence

**Internationalization:**
- Backend: `github.com/mattermost/go-i18n` - `server/i18n/`
- Frontend: `react-intl` with `FormattedMessage` components

---

*Architecture analysis: 2026-01-13*
*Update when major patterns change*