# Project Consistency Keeper - Auto-generated

**Last Updated**: 2025-01-17
**Project Root**: `./`
**Project Name**: WiseMapping Frontend
**Version**: 6.0.1

## Technology Stack

### Languages & Runtimes
- **Node.js**: >=18.0.0 (required)
- **TypeScript**: ^5.9.3 (strict mode enforced)
- **JavaScript**: ES2022 target, ES2020 modules
- **JSX**: React JSX automatic runtime

### Frameworks & Core Libraries
- **React**: ^19.0.0 (peer dependency)
- **Material-UI (MUI)**: ^7.3.4
  - `@mui/material`: ^7.3.4
  - `@mui/icons-material`: ^7.3.4
- **Emotion**: ^11.14.0+ (styled-components alternative)
- **Styled Components**: ^6.1.19

### Core Architecture Packages
- **@wisemapping/web2d**: SVG abstraction layer for chart rendering
- **@wisemapping/mindplot**: Vanilla ES6 mind map engine
- **@wisemapping/editor**: React component wrapper for mindplot
- **webapp**: Complete React application (not in current scope)

### Key Dependencies
- **html2canvas**: ^1.4.1 (for export functionality)
- **jspdf**: ^3.0.3 (PDF generation)
- **lodash**: ^4.17.21 (utility functions)
- **xml-formatter**: ^3.6.7 (XML formatting)
- **fflate**: Custom vendor version (compression)

## Toolchain Standards

### Package Management
- **Primary**: Yarn with workspaces
- **Monorepo Tool**: Lerna (independent versioning mode)
- **Workspace Structure**: `packages/*`
- **Dependency Linking**: `workspace:*` protocol

### Build System
- **Bundler**: Webpack ^5.102.1
- **Configuration**: `webpack.common.js` (shared), `webpack.prod.js`, `webpack.dev.js`
- **TypeScript Loader**: ts-loader ^9.5.4 with transpile-only mode
- **Babel**: @babel/preset-typescript ^7.28.5
- **Optimization Features**:
  - Persistent filesystem caching (`.webpack-cache`)
  - Thread-loader for parallel builds
  - Deterministic module IDs
  - Dead code elimination (`usedExports: true`)

### Development Server
- **Webpack Dev Server**: ^5.2.2
- **Port**: Configurable via `$PORT` environment variable
- **Default Ports**:
  - Editor Storybook: 6008
  - Mindplot/Storybook: 6006
  - Playground: 8081

### Code Quality & Formatting

#### ESLint Configuration
- **Version**: ^9.38.0 with flat config (`eslint.config.mjs`)
- **Presets**: 
  - `@eslint/js/recommended`
  - `eslint-plugin-react`
  - `eslint-plugin-react-hooks`
  - `eslint-plugin-cypress`
  - `eslint-plugin-storybook`
  - `eslint-config-prettier`
- **Globals**: browser, node, commonjs, jest
- **Target**: ECMAScript 2022

#### Prettier Configuration
- **Print Width**: 100
- **Tab Width**: 2
- **Single Quotes**: true
- **Trailing Commas**: `all`
- **Semicolons**: true

#### TypeScript Configuration
- **Strict Mode**: Enabled (`strict: true`)
- **Strict Null Checks**: Enabled
- **Target**: ES2022
- **Module**: ES2020
- **JSX**: React automatic runtime
- **Allow JS**: true (for mixed codebase)
- **Source Maps**: Enabled
- **Declaration**: true

### Testing Framework

#### Jest Configuration
- **Version**: ^30.2.0
- **Environment**: jsdom
- **Preset**: ts-jest
- **Transform**:
  - JS/TS: babel-jest
  - Assets: jest-transform-stub
- **Module Extensions**: js, ts, tsx
- **Verbose**: true

#### Cypress Configuration
- **Version**: ^15.5.0
- **Base URLs**: 
  - Playground: `http://localhost:8081`
  - Storybook: `http://localhost:6006`, `http://localhost:6008`
- **Features**: 
  - Visual regression testing with `cypress-image-snapshot`
  - Screenshot/video capture

### Git Workflow
- **Hooks**: Husky ^9.1.7
- **Pre-commit**: lint-staged
- **Pre-push**: `yarn lint && yarn test`
- **Branch**: Main development flow

## Project Architecture

### Directory Structure
```
.
├── packages/
│   ├── editor/          # React-based mind map editor
│   ├── mindplot/        # Core mind map engine (vanilla ES6)
│   ├── web2d/           # SVG abstraction layer
│   └── fastmind/        # Additional utilities (if present)
├── api/                 # API-related code
├── scripts/             # Build and utility scripts
├── memory-bank/         # Project documentation
└── .clinerules/         # Development guidelines
```

### Module Organization
- **Independent Versioning**: Each package uses independent versions
- **Workspace Dependencies**: Internal packages use `workspace:*`
- **Main Entry**: `src/index.ts` for all packages
- **Files**: `src` directories published (not `dist`)

### File Naming Conventions
- **TypeScript**: `.ts` for logic, `.tsx` for React components
- **Tests**: `*.test.ts`, `*.test.tsx`, or `*.cy.ts`
- **Configuration**: `*.config.js` or `*.config.ts`
- **Webpack**: `webpack.*.js`

## Development Constraints

### Package Management Commands
- **Install**: `yarn install` (not npm)
- **Clean**: `yarn clean` (removes all build artifacts)
- **Build**: `yarn build` (runs lerna build across packages)
- **Test**: `yarn test` (unit + integration tests)
- **Lint**: `yarn lint` (ESLint checks)
- **Lint Fix**: `yarn lint:fix` (ESLint with auto-fix)

### Prohibited Patterns
- **DO NOT** use npm commands (use yarn)
- **DO NOT** commit build artifacts (dist/, build/, coverage/)
- **DO NOT** use MUI without tree-shaking awareness (500KB+ impact)
- **DO NOT** disable TypeScript strict mode
- **DO NOT** skip pre-push hooks

### Required Patterns
- **ALWAYS** run `yarn lint && yarn test` before pushing
- **ALWAYS** use `workspace:*` for internal dependencies
- **ALWAYS** enable source maps in development
- **ALWAYS** write tests for new features (unit + integration)
- **ALWAYS** use Prettier for code formatting
- **ALWAYS** maintain TypeScript strict mode compliance

### Version Constraints
- **React**: ^19.0.0 (peer dependency)
- **MUI**: ^7.3.4 (critical for consistency)
- **Node**: >=18.0.0 (required)
- **TypeScript**: ^5.9.3 (latest stable)

### Bundle Optimization Requirements
- **Critical**: Pay special attention to MUI imports (tree-shaking)
- **Webpack**: Use persistent caching for rebuilds
- **Threading**: Enable parallel builds with thread-loader
- **Analyze**: Use `webpack-bundle-analyzer` for optimization

### Testing Requirements
- **Unit Tests**: Jest for logic/components
- **Integration Tests**: Cypress E2E tests
- **Visual Tests**: Cypress image snapshot regression
- **Coverage**: Maintain comprehensive test coverage
- **CI**: All tests must pass before merge

## Reference Files

### Core Configuration
- `package.json` - Root monorepo configuration
- `lerna.json` - Lerna monorepo settings
- `webpack.common.js` - Shared Webpack configuration
- `eslint.config.mjs` - ESLint flat config
- `.prettierrc.json` - Prettier formatting rules

### Package Configuration
- `packages/editor/package.json` - React editor component
- `packages/mindplot/package.json` - Core mind map engine
- `packages/web2d/package.json` - SVG abstraction layer
- `packages/*/tsconfig.json` - Package-specific TypeScript config
- `packages/*/jest.config.js` - Package-specific Jest config
- `packages/*/cypress.config.*` - Package-specific Cypress config

### Documentation
- `README.md` - Project overview
- `CONTRIBUTING.md` - Contribution guidelines
- `memory-bank/` - Comprehensive project documentation
  - `projectbrief.md` - Project overview and requirements
  - `activeContext.md` - Current development focus
  - `progress.md` - Implementation status
  - `systemPatterns.md` - Architectural patterns
  - `techContext.md` - Technology decisions

### Development Scripts
- `.husky/pre-push` - Git pre-push hook
- `scripts/check-mui-imports.sh` - MUI import validation

## Maintenance Notes

### Performance Monitoring
- Webpack build times optimization with persistent caching
- Bundle size monitoring (especially MUI impact)
- Cypress test execution speed
- TypeScript compilation performance

### Regular Updates
- Keep TypeScript at latest stable version
- Update MUI dependencies together (core + icons)
- Maintain React peer dependency compatibility
- Regular security updates for all dependencies