Skip to content

Commit 278af5e

Browse files
morbargigmorbargig
committed
docs: add design patterns and update project configuration
- Add DESIGN_PATTERNS_GUIDE.md with generic design patterns - Add INFRASTRUCTURE_GUIDE.md with project-specific details - Add STYLE_GUIDE.md with CSS/UI design system guidelines - Create minimal .cursorrules with conditional rules - Update README.md with documentation references - Update tsconfig, vite, nx, and package.json for library integration - Remove old storage hook files (useLocalStorage.ts, useDeepMemo.ts) - Update useDocumentManager hook imports - Enable mock mode login functionality
1 parent 7531f33 commit 278af5e

14 files changed

Lines changed: 750 additions & 210 deletions

‎.cursorrules‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Cursor AI Rules - Design Patterns & Code Style
2+
3+
## Core Principles
4+
5+
1. **Check recent changes** - Review git history and recent edits first
6+
2. **Remove unused code** - Delete unused imports, functions, variables, files
7+
3. **Remove old documentation** - Delete outdated docs and comments
8+
4. **Reuse code** - Use existing utilities, factories, patterns
9+
5. **Split files** - Break large files into smaller, focused files
10+
6. **Keep code simple** - Readable, straightforward code
11+
7. **Follow guidelines** - CSS/UI guidelines when applicable
12+
13+
## Code Style
14+
15+
- **Exports**: `export const functionName = () => {}` (arrow functions, named exports)
16+
- **No comments**: Code should be self-explanatory
17+
- **File extensions**: Include `.js` in relative imports for libraries (nodenext)
18+
- **Imports**: External → Internal → Relative → Types
19+
20+
## Patterns
21+
22+
### Factory Pattern
23+
If creating reusable functionality:
24+
- Use factory pattern with generics
25+
- Create typed instances from configuration
26+
- Export directly from factory using destructuring
27+
28+
### Type Guards
29+
If validating types:
30+
- Object schemas → `isType({ field: isString })`
31+
- Unknown keys → `isIndexRecord(isValue)`
32+
- Known keys → `isRecord(['key1'], isValue)`
33+
34+
### File Organization
35+
If organizing code:
36+
- One concept per file
37+
- Centralized exports in `index.ts`
38+
- Split files by responsibility
39+
40+
## Development Workflow
41+
42+
### Before Starting
43+
If beginning a task:
44+
1. Check recent changes (git history, recent edits)
45+
2. Review existing patterns in similar files
46+
3. Understand task requirements
47+
48+
### When Creating Code
49+
If writing new code:
50+
1. Define types first
51+
2. Use factory pattern if reusable
52+
3. Split files appropriately
53+
4. Reuse existing code
54+
5. Keep code simple
55+
56+
### When Refactoring
57+
If refactoring:
58+
1. Remove unused code
59+
2. Remove old documentation
60+
3. Simplify code
61+
4. Convert to patterns
62+
5. Split large files
63+
64+
## Guidelines
65+
66+
### Front/React Code
67+
If working with React/front code:
68+
- Follow patterns from INFRASTRUCTURE_GUIDE.md
69+
- Use factory pattern for hooks
70+
- Export from factories using destructuring
71+
- Keep files small and focused
72+
73+
### CSS/UI Code
74+
If working with CSS/UI:
75+
- Follow STYLE_GUIDE.md
76+
- Use Material-UI components consistently
77+
- Follow design tokens and color palette
78+
- Maintain responsive design patterns
79+
- Ensure RTL/LTR support
80+
81+
## Quick Reference
82+
83+
- **Storage hooks**: Factory → Typed hook → Re-export
84+
- **Type guards**: `isType` (objects), `isIndexRecord` (unknown keys)
85+
- **Exports**: Named exports, arrow functions, destructuring
86+
- **Files**: One concept per file, split by responsibility
87+
88+
## Reference Documents
89+
90+
- **DESIGN_PATTERNS_GUIDE.md**: Generic design patterns (read first)
91+
- **INFRASTRUCTURE_GUIDE.md**: Project-specific details
92+
- **STYLE_GUIDE.md**: CSS/UI guidelines

‎DESIGN_PATTERNS_GUIDE.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# Design Patterns & Architecture Guide
2+
3+
## Philosophy
4+
5+
This guide outlines design patterns and architectural principles that promote maintainable, scalable, and type-safe code. Focus on ideas and concepts rather than specific implementations.
6+
7+
## Core Principles
8+
9+
### 1. Separation of Concerns
10+
Keep generic utilities separate from application-specific code. Create clear boundaries between reusable libraries and business logic.
11+
12+
### 2. Factory Pattern
13+
Use factories to create typed instances from configuration. This enables reusability while maintaining type safety through generics.
14+
15+
### 3. Type-Driven Development
16+
Define types first, then implement. Use type guards for runtime validation to ensure type safety throughout the application.
17+
18+
### 4. Minimalism
19+
Write self-documenting code. Remove unnecessary comments and documentation. Prefer simple solutions over complex ones.
20+
21+
### 5. Code Reuse
22+
Always reuse code when possible. Extract common functionality into reusable utilities. Avoid duplication.
23+
24+
### 6. File Organization
25+
Split files by responsibility. Keep files small and focused. One concept per file.
26+
27+
### 7. Code Cleanup
28+
Remove unused code, old documentation, and dead code. Keep the codebase clean and maintainable.
29+
30+
---
31+
32+
## Design Patterns
33+
34+
### Factory Pattern
35+
36+
**Idea**: Create typed instances from configuration without code duplication.
37+
38+
**Structure**: Generic factory function that accepts configuration and returns typed hooks/utilities.
39+
40+
**When to Use**: When you need multiple typed instances of similar functionality with different configurations.
41+
42+
**Benefits**: Type safety, reusability, single source of truth, easy to extend.
43+
44+
---
45+
46+
### Type Guard Pattern
47+
48+
**Idea**: Provide runtime type validation while maintaining compile-time type safety.
49+
50+
**Structure**: Define types, create type guards using library functions, use guards in factories.
51+
52+
**Type Guard Rules**:
53+
- Object schemas → Use `isType` with object schema
54+
- Records with unknown keys → Use `isIndexRecord` with value type
55+
- Records with known keys → Use `isRecord` with key array and value type
56+
57+
**Benefits**: Runtime safety, type narrowing, early error detection, self-documenting validation.
58+
59+
---
60+
61+
### Layered Architecture
62+
63+
**Idea**: Separate generic utilities from application-specific code.
64+
65+
**Structure**:
66+
- Library Layer: Generic, reusable, framework-agnostic
67+
- Application Layer: App-specific types, configuration, business logic
68+
69+
**Benefits**: Reusability across projects, clear boundaries, independent testing, single responsibility.
70+
71+
---
72+
73+
### Destructuring Export Pattern
74+
75+
**Idea**: Simplify exports by eliminating intermediate variables.
76+
77+
**Structure**: Export directly from factory using destructuring instead of creating intermediate variables.
78+
79+
**Benefits**: Fewer lines, clearer intent, less memory usage, simpler code.
80+
81+
---
82+
83+
### Module Resolution Strategy
84+
85+
**Idea**: Handle module resolution correctly for different environments.
86+
87+
**Structure**: Use appropriate module resolution per environment (nodenext for libraries, bundler for apps).
88+
89+
**Benefits**: Correct module resolution, TypeScript compatibility, runtime compatibility.
90+
91+
---
92+
93+
### Mock Mode Pattern
94+
95+
**Idea**: Provide development/testing mode without external dependencies.
96+
97+
**Structure**: Check mock mode flag, route to appropriate implementation (mock or live).
98+
99+
**Benefits**: Faster development, no external dependencies, predictable test data, easy mode switching.
100+
101+
---
102+
103+
### Centralized Exports
104+
105+
**Idea**: Provide single entry point for related functionality.
106+
107+
**Structure**: Individual files export functionality, index file re-exports related items.
108+
109+
**Benefits**: Single import point, easy refactoring, clear module boundaries, better tree-shaking.
110+
111+
---
112+
113+
### Type-Safe Configuration
114+
115+
**Idea**: Ensure configuration matches types at compile time.
116+
117+
**Structure**: Define types, create configuration that matches types, TypeScript enforces correctness.
118+
119+
**Benefits**: Compile-time type checking, early error detection, self-documenting, refactor-safe.
120+
121+
---
122+
123+
## Code Style Principles
124+
125+
### Simplicity
126+
- Write simple, readable code
127+
- Remove unnecessary complexity
128+
- Prefer straightforward solutions
129+
130+
### Consistency
131+
- Follow established patterns
132+
- Use uniform code style
133+
- Maintain naming conventions
134+
135+
### Type Safety
136+
- Leverage TypeScript fully
137+
- Use generics for reusability
138+
- Use type guards for validation
139+
140+
### Organization
141+
- Split files by responsibility
142+
- Keep files focused
143+
- Group related functionality
144+
145+
### Cleanup
146+
- Remove unused code
147+
- Delete old documentation
148+
- Clean up dead code
149+
150+
---
151+
152+
## Development Workflow
153+
154+
### Before Starting
155+
1. Check recent changes to understand current state
156+
2. Review existing patterns in similar files
157+
3. Understand the task requirements
158+
159+
### When Creating Code
160+
1. Define types first
161+
2. Create type guards
162+
3. Use factory pattern for reusable functionality
163+
4. Split files appropriately
164+
5. Reuse existing code when possible
165+
6. Keep code simple and readable
166+
167+
### When Refactoring
168+
1. Remove unused code
169+
2. Simplify existing code
170+
3. Convert to established patterns
171+
4. Remove intermediate variables
172+
5. Clean up old documentation
173+
174+
### Code Review
175+
1. Remove unused imports
176+
2. Delete dead code
177+
3. Simplify complex logic
178+
4. Ensure consistency
179+
5. Follow CSS style guidelines
180+
181+
---
182+
183+
## Best Practices
184+
185+
### ✅ Do
186+
- Reuse code through factories and utilities
187+
- Split files by responsibility
188+
- Remove unused code and documentation
189+
- Keep code simple and readable
190+
- Check recent changes before starting
191+
- Follow CSS style guidelines
192+
- Use type guards for validation
193+
- Leverage TypeScript generics
194+
195+
### ❌ Don't
196+
- Duplicate code unnecessarily
197+
- Create large, monolithic files
198+
- Keep unused or dead code
199+
- Add unnecessary complexity
200+
- Ignore existing patterns
201+
- Skip code cleanup
202+
- Forget type safety
203+
- Mix concerns between layers
204+
205+
---
206+
207+
## Pattern Selection Guide
208+
209+
| Need | Pattern | Concept |
210+
|------|---------|---------|
211+
| Multiple typed instances | Factory Pattern | Configuration-driven creation |
212+
| Runtime validation | Type Guards | Type-safe validation |
213+
| Code reuse | Factory Pattern | Generic implementation |
214+
| Development mode | Mock Mode | Flag-based routing |
215+
| Related exports | Centralized Exports | Single entry point |
216+
| Type safety | Type-Safe Configuration | Compile-time checking |
217+
218+
---
219+
220+
## Summary
221+
222+
These patterns promote:
223+
224+
1. **Reusability**: Generic code for multiple use cases
225+
2. **Type Safety**: Leverage TypeScript fully
226+
3. **Maintainability**: Clear structure and patterns
227+
4. **Simplicity**: Minimal, clean code
228+
5. **Consistency**: Uniform patterns throughout
229+
6. **Cleanliness**: Remove unused code and documentation
230+
231+
Focus on ideas and principles. Implementation details should follow these patterns naturally.

0 commit comments

Comments
 (0)