actor_sample/model/
mod.rs

1//! # Resource Models & Data Transfer Objects
2//!
3//! This module contains the **pure data structures** that represent the core business entities
4//! (resources) in the system. These types are shared across the entire application and form
5//! the public contract between actors and their clients.
6//!
7//! ## Architecture Principles
8//!
9//! ### 1. Pure Data Structures
10//!
11//! All types in this module are **plain data** with no business logic:
12//!
13//! - No methods (except constructors and simple getters)
14//! - No dependencies on framework code
15//! - Easily serializable (ready for JSON, databases, etc.)
16//! - Can be used in any layer of the application
17//!
18//! ### 2. DTOs vs Entities
19//!
20//! We distinguish between different types of data structures:
21//!
22//! **DTO (Data Transfer Object)** - A design pattern for objects that carry data between
23//! processes or layers. DTOs have no business logic, only data fields. In this framework,
24//! we use DTOs to represent different "views" of an entity for different operations.
25//!
26//! **Entity** - The full resource with all fields:
27//! ```rust
28//! pub struct User {
29//!     pub id: String,
30//!     pub name: String,
31//!     pub email: String,
32//! }
33//! ```
34//!
35//! **Create DTO** - Parameters for creating a new resource (no ID):
36//! ```rust
37//! pub struct UserCreate {
38//!     pub name: String,
39//!     pub email: String,
40//! }
41//! ```
42//!
43//! **Update DTO** - Partial updates (all fields optional):
44//! ```rust
45//! pub struct UserUpdate {
46//!     pub name: Option<String>,
47//!     pub email: Option<String>,
48//! }
49//! ```
50//!
51//! This pattern ensures type safety: you **can't** create a user without a name,
52//! but you **can** update just the email without touching the name.
53//!
54//! ## Resource Models
55//!
56//! A **resource** is a business entity that the system manages (User, Product, Order).
57//! Each resource has its own actor and follows the CRUD pattern.
58//!
59//! ### [`User`]
60//!
61//! Represents a registered user in the system. Users are referenced by orders
62//! to track who placed each order.
63//!
64//! ### [`Product`]
65//!
66//! Represents a product available for purchase. Products track inventory levels
67//! and support stock reservation for order fulfillment.
68//!
69//! ### [`Order`]
70//!
71//! Represents a customer order. Orders reference both a user (who placed it)
72//! and a product (what was ordered), demonstrating actor coordination.
73//!
74//! ## Design Patterns
75//!
76//! ### Separation from Actor Logic
77//!
78//! These models are **separate** from the actor implementations:
79//!
80//! - **Models** (`src/model/`) - Pure data, no framework dependencies
81//! - **Actors** (`src/*_actor/`) - Business logic via [`ActorEntity`](actor_framework::ActorEntity) trait
82//!
83//! This separation allows:
84//! - Models to be used in non-actor contexts (HTTP handlers, CLI, etc.)
85//! - Easy serialization without actor-specific concerns
86//! - Clear boundaries between data and behavior
87//!
88//! ### Future: Multi-Crate Support
89//!
90//! This structure is designed to support splitting into multiple crates:
91//!
92//! ```text
93//! my-resources/     # Pure resource models (this module)
94//! my-actors/        # Actor implementations
95//! my-framework/     # Generic framework code
96//! ```
97//!
98//! The models have **zero dependencies** on the framework, making them
99//! easy to extract into a shared library.
100
101pub mod order;
102pub mod product;
103pub mod user;
104
105pub use order::*;
106pub use product::*;
107pub use user::*;
actor_sample/model/mod.rs

actor_sample/model/
mod.rs
