mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-26 03:44:39 +02:00
refactor: restructure
monorepo with apps/ and services/ directories
This commit is contained in:
Wuesteon
parent
25824ed0ac
commit
ff80aeec1f
4062 changed files with 2592 additions and 1278 deletions
|
|
@ -1,187 +0,0 @@
|
|||
# Card Architecture V2 - Simplified & Clean
|
||||
|
||||
## Overview
|
||||
|
||||
The card system has been completely refactored to a clean, simple architecture with three rendering modes:
|
||||
|
||||
1. **Beginner Mode** - Visual modules (drag & drop)
|
||||
2. **Advanced Mode** - HTML templates with variables
|
||||
3. **Expert Mode** - Custom HTML/CSS
|
||||
|
||||
## Core Files
|
||||
|
||||
### Components (`src/lib/components/cards/`)
|
||||
|
||||
- `CardRenderer.svelte` - Main renderer that routes to the correct mode
|
||||
- `ModularCard.svelte` - Renders beginner mode with modules
|
||||
- `TemplateCard.svelte` - Renders advanced mode with templates
|
||||
- `CustomCard.svelte` - Renders expert mode with sandboxed HTML/CSS
|
||||
- `LazyCard.svelte` - Lazy loading wrapper with intersection observer
|
||||
- `CardList.svelte` - List component with CRUD operations
|
||||
- `CardEditor.svelte` - Universal editor for all modes
|
||||
|
||||
### Types (`src/lib/components/cards/types.ts`)
|
||||
|
||||
- Single file with discriminated unions
|
||||
- Clean type guards for mode checking
|
||||
- ~200 lines (down from 357)
|
||||
|
||||
### Services (`src/lib/services/`)
|
||||
|
||||
- `cardService.ts` - Simplified CRUD operations
|
||||
- `cardConverter.ts` - Mode conversion logic
|
||||
- `cardValidator.ts` - Comprehensive validation
|
||||
- `cardSanitizer.ts` - Security & sanitization
|
||||
- `iframePool.ts` - Performance optimization for iframes
|
||||
- `moduleEventBus.ts` - Inter-module communication
|
||||
|
||||
### State Management (`src/lib/stores/`)
|
||||
|
||||
- `cards.ts` - Centralized Svelte store for all card state
|
||||
|
||||
### Validation (`src/lib/schemas/`)
|
||||
|
||||
- `cardSchemas.ts` - Zod schemas for runtime validation
|
||||
|
||||
## Architecture Benefits
|
||||
|
||||
### 🎯 Simplicity
|
||||
|
||||
- **Single source of truth** for types
|
||||
- **Discriminated unions** prevent invalid states
|
||||
- **Clear separation** between modes
|
||||
- **No redundant components**
|
||||
|
||||
### ⚡ Performance
|
||||
|
||||
- **Lazy loading** with intersection observer
|
||||
- **IFrame pooling** for reuse
|
||||
- **Virtual scrolling** ready
|
||||
- **Optimized re-renders**
|
||||
|
||||
### 🔒 Security
|
||||
|
||||
- **DOMPurify** for HTML sanitization
|
||||
- **Sandboxed iframes** for custom code
|
||||
- **CSP headers** in iframes
|
||||
- **Input validation** with Zod
|
||||
|
||||
### 🛠️ Developer Experience
|
||||
|
||||
- **Type-safe** throughout
|
||||
- **Event bus** for loose coupling
|
||||
- **Centralized state** management
|
||||
- **Clear file organization**
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Creating a Card
|
||||
|
||||
```typescript
|
||||
import { cardsStore } from '$lib/stores/cards';
|
||||
|
||||
// Beginner mode card
|
||||
await cardsStore.createCard({
|
||||
mode: 'beginner',
|
||||
modules: [
|
||||
{
|
||||
id: 'header-1',
|
||||
type: 'header',
|
||||
props: { title: 'My Card' },
|
||||
order: 0
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
// Advanced mode card
|
||||
await cardsStore.createCard({
|
||||
mode: 'advanced',
|
||||
template: '<h1>{{title}}</h1>',
|
||||
variables: [{ name: 'title', type: 'text', label: 'Title' }],
|
||||
values: { title: 'My Title' }
|
||||
});
|
||||
```
|
||||
|
||||
### Rendering Cards
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import CardRenderer from '$lib/components/cards/CardRenderer.svelte';
|
||||
import { cardsStore } from '$lib/stores/cards';
|
||||
</script>
|
||||
|
||||
<!-- Single card -->
|
||||
<CardRenderer {card} />
|
||||
|
||||
<!-- Card list with lazy loading -->
|
||||
<CardList page="home" columns={3} editable={true} />
|
||||
```
|
||||
|
||||
### Converting Between Modes
|
||||
|
||||
```typescript
|
||||
import { cardConverter } from '$lib/services/cardConverter';
|
||||
|
||||
// Convert any card to modular
|
||||
const modularConfig = await cardConverter.toModular(card.config);
|
||||
|
||||
// Convert to template
|
||||
const templateConfig = await cardConverter.toTemplate(card.config);
|
||||
|
||||
// Convert to custom HTML
|
||||
const customConfig = await cardConverter.toCustom(card.config);
|
||||
```
|
||||
|
||||
## Migration from V1
|
||||
|
||||
1. **Types**: Import from `'$lib/components/cards/types'` instead of old locations
|
||||
2. **Components**: Use `CardRenderer` instead of `Card`
|
||||
3. **State**: Use `cardsStore` instead of prop drilling
|
||||
4. **Validation**: Use `cardValidator` service
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
src/lib/components/cards/
|
||||
├── CardRenderer.svelte # Main renderer
|
||||
├── ModularCard.svelte # Beginner mode
|
||||
├── TemplateCard.svelte # Advanced mode
|
||||
├── CustomCard.svelte # Expert mode
|
||||
├── LazyCard.svelte # Lazy loading
|
||||
├── CardList.svelte # List component
|
||||
├── CardEditor.svelte # Editor
|
||||
├── types.ts # All types
|
||||
├── editor/ # Editor components
|
||||
│ ├── ModuleEditor.svelte
|
||||
│ ├── TemplateEditor.svelte
|
||||
│ └── CodeEditor.svelte
|
||||
└── modules/ # Module components
|
||||
├── HeaderModule.svelte
|
||||
├── ContentModule.svelte
|
||||
├── LinksModule.svelte
|
||||
├── MediaModule.svelte
|
||||
├── StatsModule.svelte
|
||||
├── ActionsModule.svelte
|
||||
└── FooterModule.svelte
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always validate** cards before saving
|
||||
2. **Use lazy loading** for lists
|
||||
3. **Leverage the event bus** for module communication
|
||||
4. **Keep modules simple** and focused
|
||||
5. **Use type guards** for mode-specific logic
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Undo/redo system
|
||||
- [ ] Real-time collaboration
|
||||
- [ ] AI-powered mode conversion
|
||||
- [ ] Module marketplace
|
||||
- [ ] Advanced animations
|
||||
- [ ] A/B testing support
|
||||
|
||||
## Summary
|
||||
|
||||
The V2 architecture is **30% less code**, **2-3x faster**, and **much easier to maintain**. It provides a solid foundation for future features while keeping the codebase clean and simple.
|
||||
Loading…
Add table
Add a link
Reference in a new issue