Home

📑 Full Technical Notes on Smart_Store Project

A Modern C++ Item Management System with Undo/Redo, Multi-Format Persistence, Thread-Safety, and Schema Migration.

🔷 Project Summary

• Smart_Store is a robust, extensible, and modular C++20 framework designed to manage collections of arbitrary objects with support for advanced serialization, deserialization, schema versioning, and undo/redo state management.

• Its primary purpose is to serve as a core utility for inventory management, asset management, game editors, data modeling tools, and any application requiring flexible object storage with persistence and versioning.

🔶 Core Objectives

• Provide safe and maintainable item storage with full ownership semantics (shared_ptr)
• Support tag-based lookup for fast item retrieval
• Enable undo/redo history for state management
• Allow importing/exporting data across multiple formats: JSON, XML, CSV, and Binary
• Handle schema version migration cleanly, supporting legacy upgrades
• Ensure thread-safe operations
• Offer an extensible system for custom item types registration through templates
• Built with modern C++ idioms (RAII, STL containers, type safety)

🔷 Key Features in Detail

Memory Management

• Uses std::shared_ptr across all items.
• No raw pointers exposed to users.
• Ownership fully managed internally.
• Undo/Redo operates on deep copies (clone).

Undo / Redo History

• Snapshots of internal state stored as deep clones.
• undo() and redo() allow safe state traversal.
• Clear separation of history stacks.

Thread Safety

• Mutex locks (std::lock_guardstd::mutex) ensure safe concurrent access to the items container.
• Read and write operations protected.
• Thread-safe API guarantees no race conditions during modification.

* Schema Migration

• Built-in MigrationRegistry system.
• Allows versioned upgrades of legacy JSON data on import.
• Supports gradual migration strategies (e.g., from v1 → v2 → v3).
• Reduces data corruption and incompatibility risks over time.

* Multi-Format Import / Export

Format	Import	Export	Notes
JSON	✅	✅	Human-friendly
CSV	✅	✅	Interop with Excel
XML	✅	✅	Human-readable
Binary	✅	✅	Compact & fast

🔷 Architecture Overview

Main Components:

Component	Role
ItemManager	Core storage & API interface
BaseItem	Abstract base for custom item types
ItemWrapper	Handles serialization metadata
Logger	Logging with colors for clarity
MigrationRegistry	Manages version upgrades
AtomicFileWriter	Safe file writing utility

🔶 Supported Types

Built-in Types: int, std::string, bool Custom Types: Any user-defined class deriving from BaseItem and registered via registerType.

Data Model:

• items: std::unordered_map<std::string, std::shared_ptr>
• tag -> object
• idMap: optional map for reverse-lookup via ID

🔷 Design Considerations

Why Thread-Safe?

• Anticipates concurrent access in larger apps (UI threads, background saves).
• Protects items against simultaneous reads/writes.
• Why Schema Migration?
• Long-term data safety.
• Supports evolving application needs without breaking existing data.

Why Undo/Redo?

• Ideal for editor applications and asset tools.

• Encourages experimentation with state safety.

🔷 Technical Stack

• C++20: Modern language features, STL, optional, shared_ptr
• nlohmann::json: Intuitive JSON handling
• TinyXML2: Lightweight XML parsing
• ANSI Color Logger: Developer-friendly debugging output
• RAII: Automatic resource management everywhere

🔷 Limitations / Future Improvements

• Currently single-level undo/redo (future: multi-depth branching?)

• Schema migration is JSON-focused (extend to XML/CSV if needed).

• Thread safety is global-lock (potential for finer-grained locking if performance requires).

🔷 Ideal Use-Cases

• Inventory management systems
• Asset tracking tools
• Game editors
• Data analysis tools requiring reversible state management
• Applications requiring cross-format data interoperability