Core Concepts & Entities

Core Concepts & Entities define the foundational building blocks and operational principles of the platform. They provide a unified model for managing resources, controlling access, and orchestrating interactions across various services. Understanding these core elements is crucial for integrating with the platform, extending its capabilities, and building robust applications.

Purpose

The primary purpose of Core Concepts & Entities is to establish a consistent, extensible, and secure framework for managing all platform resources and their interactions. This framework simplifies development by abstracting underlying infrastructure complexities, enforcing security policies, and providing standardized mechanisms for data access and event processing. It ensures interoperability and maintainability across diverse components and applications built on the platform.

Key Entities

The platform operates on a set of fundamental entities that represent addressable resources and organizational structures. These entities are the primary units of interaction for developers.

Resource

A Resource is the most fundamental entity, representing any addressable component or data within the platform. This can range from a data object, a service endpoint, a configuration setting, or a computational unit. Each Resource possesses a unique identifier, a type, and associated metadata.

Developers interact with Resource objects to perform operations such as creation, retrieval, update, and deletion.

from core_sdk import ResourceManager, Resource

# Example: Creating a new resource
new_resource_data = {
    "name": "my-service-instance",
    "type": "ServiceInstance",
    "region": "us-east-1",
    "config": {"port": 8080}
}
new_resource = ResourceManager.create_resource(new_resource_data)
print(f"Created Resource ID: {new_resource.id}")

# Example: Retrieving a resource
retrieved_resource = ResourceManager.get_resource(new_resource.id)
print(f"Retrieved Resource Name: {retrieved_resource.name}")

Tenant

A Tenant represents an isolated operational environment within the platform, typically corresponding to a customer, organization, or project. Tenants provide logical separation of resources, data, and configurations, ensuring multi-tenancy and data isolation. All resources are scoped within a specific Tenant.

Operations on resources implicitly or explicitly require a Tenant context.

from core_sdk import TenantManager, Tenant

# Example: Getting the current tenant context
current_tenant = TenantManager.get_current_tenant()
print(f"Current Tenant ID: {current_tenant.id}")

# Example: Listing resources for a specific tenant
tenant_resources = ResourceManager.list_resources(tenant_id=current_tenant.id, resource_type="ServiceInstance")
for res in tenant_resources:
    print(f"  - {res.name} ({res.id})")

Policy

A Policy defines a set of rules that govern access to resources and permissible actions within the platform. Policies are central to the platform's security model, enabling fine-grained authorization. They specify who (principals) can do what (actions) on which resources, under what conditions.

Policies are typically attached to Tenant objects, User objects, or specific Resource objects.

from core_sdk import PolicyManager, Policy

# Example: Defining a policy to allow read access to a specific resource type
read_policy_definition = {
    "name": "read-service-instances",
    "statements": [
        {
            "effect": "allow",
            "actions": ["resource:read"],
            "resources": ["arn:platform:resource:ServiceInstance:*"],
            "principals": ["user:dev-team"]
        }
    ]
}
new_policy = PolicyManager.create_policy(read_policy_definition)
print(f"Created Policy ID: {new_policy.id}")

# Example: Attaching a policy to a user group
PolicyManager.attach_policy_to_principal(new_policy.id, "group:developers")

Event

An Event represents a significant occurrence or state change within the platform. Events are immutable records that capture what happened, when it happened, and relevant context. The platform's eventing system uses these to enable reactive programming models, auditing, and inter-service communication.

Developers can publish custom events or subscribe to system-generated events.

from core_sdk import EventPublisher, EventSubscriber, Event

# Example: Publishing a custom event
custom_event_data = {
    "type": "Custom.ServiceStatusChange",
    "source": "my-service",
    "detail": {"service_id": "svc-123", "status": "restarted"}
}
EventPublisher.publish(custom_event_data)
print("Custom event published.")

# Example: Subscribing to events (simplified representation)
def handle_resource_created(event: Event):
    print(f"Resource created: {event.detail.get('resource_id')} of type {event.detail.get('resource_type')}")

subscriber = EventSubscriber.create_subscriber("Resource.Created", handle_resource_created)
# In a real system, this would register a callback or a queue listener

Core Capabilities

The platform provides several core capabilities that leverage these entities to deliver a robust and secure environment.

Entity Lifecycle Management

The platform offers comprehensive lifecycle management for all Resource types. This includes standardized APIs for creating, retrieving, updating, and deleting resources, along with mechanisms for versioning, archiving, and soft-deletion. The ResourceManager provides a unified interface for these operations, abstracting the underlying storage and service-specific implementations.

Best Practice: Always use the ResourceManager for entity operations to ensure consistency, policy enforcement, and proper event generation. Avoid direct manipulation of underlying data stores.

Access Control & Authorization

Access to all resources is governed by the platform's robust access control system, built upon Policy entities. This system enforces authorization checks at every interaction point, ensuring that only authorized principals can perform permitted actions on specific resources. The system supports role-based access control (RBAC), attribute-based access control (ABAC), and fine-grained permissions.

Developers define policies using a declarative language, specifying allow or deny statements for actions on resources. The PolicyManager facilitates policy creation, attachment, and evaluation.

Integration Point: When developing new services or extending existing ones, integrate authorization checks using the AuthService.check_permission() method at critical operation boundaries.

from core_sdk import AuthService

# Example: Checking if a user has permission to delete a resource
user_id = "user-alice"
resource_arn = "arn:platform:resource:ServiceInstance:svc-123"
action = "resource:delete"

if AuthService.check_permission(user_id, resource_arn, action):
    print(f"User {user_id} is authorized to {action} {resource_arn}.")
    # Proceed with deletion
else:
    print(f"User {user_id} is NOT authorized to {action} {resource_arn}.")
    # Deny operation

Event-Driven Interactions

The platform features a highly scalable eventing system that enables asynchronous communication and reactive programming. All significant state changes and operations on core entities generate Event objects, which are then published to a central event bus. Services can subscribe to specific event types, allowing them to react to changes without tight coupling.

This capability is crucial for building loosely coupled microservices, auditing, real-time analytics, and triggering automated workflows.

Performance Consideration: While event-driven architectures offer scalability, ensure event handlers are idempotent to prevent issues from duplicate event delivery. Design event payloads to be concise, containing only necessary information or references to larger data.

Metadata & Tagging

All Resource entities support extensible metadata and tagging. Metadata provides structured information about a resource (e.g., creation timestamp, owner, status), while tags are key-value pairs for arbitrary categorization (e.g., environment:production, project:alpha). This capability enhances resource discoverability, management, and cost allocation.

Developers can add, update, and query resources based on their metadata and tags.

from core_sdk import ResourceManager

# Example: Adding tags to an existing resource
resource_id = "svc-123"
ResourceManager.add_tags(resource_id, {"cost_center": "engineering", "owner": "dev-team"})

# Example: Querying resources by tag
prod_services = ResourceManager.list_resources(tags={"environment": "production", "type": "ServiceInstance"})
for service in prod_services:
    print(f"Production Service: {service.name}")

Common Use Cases

• Multi-Tenant Application Development: Building applications that serve multiple customers, each with their isolated data and configurations, leveraging Tenant and Resource entities.
• Automated Resource Provisioning: Using the ResourceManager to programmatically create and configure infrastructure components or application services, often triggered by events or CI/CD pipelines.
• Custom Authorization Logic: Implementing fine-grained access control for application-specific resources by defining and attaching custom Policy entities.
• Real-time Monitoring & Alerting: Subscribing to Event streams to detect critical system changes, trigger alerts, or update dashboards.
• Auditing and Compliance: Leveraging the immutable Event log for comprehensive auditing of all resource operations and state changes.
• Resource Discovery & Management: Querying Resource entities based on type, metadata, or tags to build management consoles or automation scripts.

Integration Patterns & Best Practices

• SDK Usage: Always interact with Core Concepts & Entities through the provided SDK (e.g., core_sdk). This ensures adherence to platform contracts, proper authentication, and policy enforcement.
• Tenant Context: Explicitly manage or retrieve the Tenant context for all resource operations. Most SDK methods will infer it from the authentication token, but be aware of cross-tenant operations if your application requires them.
• Idempotent Operations: Design your resource creation and update logic to be idempotent. Retrying an operation should yield the same result without unintended side effects.
• Event-Driven Design: Embrace the eventing system for inter-service communication. Avoid direct synchronous calls between services where asynchronous eventing can achieve loose coupling and better scalability.
• Policy-as-Code: Manage Policy definitions as code in version control systems. This allows for consistent, auditable, and automated deployment of security configurations.
• Resource Naming Conventions: Establish clear and consistent naming conventions for Resource entities to improve discoverability and management.

Limitations & Considerations

• Eventual Consistency: The eventing system operates on an eventual consistency model. While events are delivered reliably, there might be a slight delay before all subscribers process them and reflect state changes.
• Policy Complexity: While powerful, overly complex Policy definitions can become difficult to manage and debug. Strive for simplicity and modularity in policy design.
• Resource Limits: Be aware of platform-defined limits on the number of resources per tenant, API request rates, and event throughput. Design your applications to handle these limits gracefully, implementing retry mechanisms and back-offs where appropriate.
• Performance of Large Queries: Querying Resource entities with very broad or complex tag/metadata filters across a massive dataset can impact performance. Optimize queries by specifying resource types, tenant IDs, and indexed metadata fields.
• Schema Evolution: When defining custom Resource types or extending metadata, plan for schema evolution. Backward compatibility is crucial for long-lived applications.