alebl/magic-the-gathering-deckforge

Purpose and Runtime

MTG Deck Forge is a local-first Magic: The Gathering card search, deck-building, analysis, proxy-printing, and playtest application. The primary runtime is a React 19/TypeScript renderer built by Vite; it runs either in a browser or inside Electron. Electron’s privileged boundary is defined by electron/index.ts and electron/preload.ts.

Application Composition and Entry Points

The renderer starts at src/main.tsx, mounts the application in src/App.tsx, and is framed by shared navigation/layout in src/components/layout/RootLayout.tsx. Domain UI is organized around card collection, deck editing, statistics, and playtesting rather than route-specific server endpoints. Shared types provide the central domain model: src/types/Card.ts, src/types/Deck.ts, and src/types/Playtest.ts.

Card Discovery and Collection

Card discovery is driven by debounced Scryfall-backed search and filter state through src/hooks/useCardSearch.ts and src/hooks/useSearchFilters.ts; results render through src/components/card/CardGrid.tsx and card details/actions through src/components/card/CardDetailModal.tsx. Collection ownership and filtering form a separate local concern in src/hooks/useCollection.ts, src/hooks/useCollectionOwnership.ts, and src/components/collection/CollectionManager.tsx. This boundary keeps remote card metadata distinct from user-owned inventory.

Deck Lifecycle and Persistence

Deck editing is centered on src/components/deck/DeckEditWorkspace.tsx, with global selected-deck and deck-list state in src/store/useDeckStore.ts. High-level lifecycle actions—create/edit/save/load/delete—are coordinated in src/hooks/useDeckManager.ts and src/hooks/useDeckActions.ts. Persistent local storage is configured in src/db/database.ts, while deck interchange/version capabilities live in src/services/deckImportService.ts, src/services/deckShare.ts, and src/services/deckVersionService.ts. Decks can therefore flow between UI state, IndexedDB, and import/export files without requiring an application backend.

Validation, Suggestions, and Analytics

Pure domain calculations sit behind the editing UI: legality and deck rules in src/utils/deckValidator.ts, deck metrics in src/utils/deckStatistics.ts, and automated recommendations in src/utils/deckSuggestions.ts. Their visual consumers are src/components/deck/DeckValidationBadge.tsx, src/components/stats/DeckStats.tsx, and src/components/deck/DeckSuggestionsModal.tsx. Scryfall is also an external legality/data authority, while local calculations provide immediate deck feedback.

Tokens, Printing, and Playtesting

Token requirements are derived from deck card data through src/hooks/useDeckTokens.ts and managed in src/components/deck/DeckTokensTab.tsx. Proxy-print configuration and output are handled by src/hooks/useProxyPrint.ts and src/components/deck/DeckProxyPrint.tsx. The playtest simulator has isolated interaction state in src/components/playtest/PlaytestContext.tsx, behavior in src/hooks/usePlaytestSimulator.ts, and its primary workspace in src/components/playtest/PlaytestSimulator.tsx; it consumes an assembled deck but models transient gameplay separately from persisted deck data.

Cross-Cutting Boundaries

Localization is initialized in src/plugins/i18n.ts with language catalogs in src/locales/en.ts, src/locales/es.ts, and src/locales/pt.ts. Application-level preferences include collection settings in src/store/useCollectionSettings.ts and browser persistence keys in src/constants/storage.ts. Network availability is surfaced through src/hooks/useOnlineStatus.ts, important because card search and legality checks depend on the external Scryfall API, while decks and collections remain available from local IndexedDB.