Home

🛍️ Smart_Store

Technical Notes

---

Project Summary

Smart_Store is a robust, extensible, and modular C++20 framework for managing collections of arbitrary objects with advanced serialization, schema migration, and undo/redo state management. It is ideal for inventory management, asset tracking, game editors, and any application needing flexible object storage with persistence and versioning.

Smart_Store isn’t just a C++ framework; it’s a living ecosystem. Think of it like a woman nurturing life: when an object is added, it’s not just stored, it evolves. Hands, eyes, and a voice, their functionality emerges naturally as the system recognizes its identity and extends it. I designed Smart_Store as a womb for intelligent objects. Instead of rigid definitions and manual wiring, objects grow their own traits through schema awareness, custom type registration, and multi-format serialization, all written in pure, raw C++20. Undo/redo, thread safety, migration, it’s all embedded, not bolted on. This isn’t just engineering, it’s biological architecture. I wanted every interaction with the system to feel organic, reactive, alive. And the result? A framework that thinks like a developer, behaves like a tool, and responds like a living system.

---

Core Objectives

• Safe, maintainable item storage using std::shared_ptr
• Tag-based lookup for fast item retrieval
• Undo/redo history for state management
• Import/export across JSON, XML, CSV, and Binary formats
• Clean schema migration for legacy upgrades
• Thread-safe operations
• Extensible custom type registration via templates
• Built with modern C++ idioms (RAII, STL, type safety)

---

Key Features

Memory Management

• Uses std::shared_ptr for all items
• No raw pointers exposed
• Ownership fully managed internally
• Undo/redo operates on deep clones

Undo / Redo History

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

Thread Safety

• Mutex locks (std::lock_guard<std::mutex>) for safe concurrent access
• Read/write operations protected
• Thread-safe API prevents race conditions

Schema Migration

• Built-in MigrationRegistry system
• Versioned upgrades of legacy JSON data on import
• Gradual migration strategies (e.g., v1 → v2 → v3)
• Reduces data corruption and incompatibility

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 item types
ItemWrapper	Handles serialization metadata
Logger	Color logging for clarity
MigrationRegistry	Manages version upgrades
AtomicFileWriter	Safe file writing utility
Json_traits	Type traits for safe, automatic JSON (de)serialization

Supported Types

• Built-in: int, std::string, bool
• Custom: Any user-defined class registered via registerType

Data Model

• items: std::unordered_map<std::string, std::shared_ptr<BaseItem>> (tag → object)
• idMap: Optional map for reverse-lookup by ID

---

Design Considerations

Thread Safety

• Anticipates concurrent access (UI threads, background saves)
• Protects items against simultaneous reads/writes

Schema Migration

• Ensures long-term data safety
• Supports evolving needs without breaking data

Undo/Redo

• Ideal for editors and asset tools
• Encourages experimentation with state safety

---

Technical Stack

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

---

Limitations & Future Improvements

• Single-level undo/redo (future: multi-depth branching)
• Schema migration is JSON-focused (extend to XML/CSV)
• Thread safety is global-lock (potential for finer-grained locking)

Ideal Use Cases

• Inventory management systems
• Asset tracking tools
• Game editors
• Data analysis tools with reversible state
• Apps needing cross-format data interoperability

---

Work flow in Smart_Store:

---

Getting Started

Basic Usage Example

#include "t_manager/ItemManager.h"

struct MyType {
    int value;
    // ...
};

int main() {
    ItemManager manager;
    manager.addItem(std::make_shared<MyType>(MyType{42}), "my_tag");
    manager.displayByTag("my_tag");
    manager.exportToFile_Json("data.json");
    manager.undo();
    return 0;
}

Output:

Integration

• Add Smart_Store to your CMake project and link dependencies (nlohmann::json, TinyXML2).
• Integration guide

---

API Reference (Key Methods)

Method	Description
addItem(obj, tag)	Add an item with a tag
removeByTag(tag)	Remove item by tag
displayByTag(tag)	Display item details
undo() / redo()	Undo/redo last state change
exportToFile_JSON(filename)	Export all items to JSON
importFromFile_JSON(filename)	Import items from JSON
registerType<T>()	Register a custom type

See source code for full API details.

---

Error Handling & Logging

• Errors are reported via exceptions and color-coded logger output.
• Logging is extensible; you can add custom log levels or output destinations.

---

Extensibility

• Add new formats by extending import/export methods.
• Implement custom serialization for user types by specializing traits or providing to_json/from_json.
• Schema migration strategies can be customized in MigrationRegistry.

---

Performance Notes

• Designed for fast lookup and serialization.
• Thread safety uses global mutex; for very large datasets, consider finer-grained locking.
• Undo/redo uses deep clones; optimize for large objects as needed.

---

Community & Support

• Ask questions, report bugs, or request features via GitHub Issues.
• See README for contribution guidelines.

---

License & Contribution

• MIT License. Contributions welcome!
• See README and LICENSE for details.