Core Concepts
DRFT is built around a few key concepts that work together to manage your resources.
Resources
Resources are the building blocks of your stack. They represent the things you want to manage - whether that's cloud infrastructure (servers, databases, networks), project configuration, application settings, or any other declarative resource.
final resource = VirtualMachine(
name: 'web-server',
image: 'ubuntu-22.04',
size: 'medium',
);
Resources are:
- Immutable - Once created, properties don't change
- Type-safe - Dart's type system ensures correctness
- Declarative - You describe what you want, not how to get it
Learn more: Resources Guide
Providers
Providers are the bridge between DRFT and the actual platforms or systems (AWS, Firebase, App Store Connect, etc.). They handle the creation, reading, updating, and deletion of resources.
final provider = AwsProvider(
region: 'us-east-1',
credentials: awsCredentials,
);
Each provider knows how to:
- Create resources in its platform
- Read current resource state
- Update existing resources
- Delete resources
Learn more: Providers Guide
State
State represents the current state of your resources. DRFT tracks:
- What resources exist
- Their current properties
- Their relationships
State is stored locally (or remotely with a state backend) and is used to:
- Compare desired vs actual resources
- Plan changes
- Track what's been created
Learn more: State Management
Stacks
A Stack is a collection of resources and providers that define a complete resource configuration.
final stack = DrftStack(
name: 'production',
providers: [AwsProvider(region: 'us-east-1')],
resources: [
VirtualMachine(name: 'server-1'),
Database(name: 'main-db'),
],
);
Stacks provide:
- Resource organization
- Provider configuration
- State management
- Planning and execution
Planning
Planning is the process of comparing desired resources (your code) with actual resources (what exists) to determine what changes need to be made.
final plan = await stack.plan();
// Plan shows: create, update, or delete operations
A plan shows you:
- What will be created
- What will be updated
- What will be deleted
- What will remain unchanged
Execution
Execution is applying the plan to actually make changes to your resources.
final result = await stack.apply(plan);
// Changes are now applied
Execution is:
- Safe - You always plan first
- Idempotent - Running twice has the same result
- Transactional - Changes are atomic where possible
Dependencies
Resources can depend on other resources. DRFT automatically:
- Orders operations correctly
- Ensures dependencies are created first
- Handles deletion in reverse order
final vpc = Vpc(name: 'main-vpc');
final subnet = Subnet(
name: 'main-subnet',
vpcId: vpc.id, // Dependency
);
Learn more: Dependent Resources
Data Sources
Data sources are read-only resources that represent external infrastructure managed outside of DRFT. They cannot be created, updated, or deleted through DRFT, but they can be read to verify existence and provide information to other resources.
// Data source - represents an existing Firebase project
final project = FirebaseProject(
id: 'project',
projectId: 'my-project-id', // Must exist externally
displayName: 'My Project',
);
// Regular resource - depends on the data source
final app = FirebaseApp(
id: 'app',
projectId: project.projectId, // Uses project information
platform: FirebaseAppPlatform.ios,
displayName: 'My App',
);
Data sources:
- Are only read (never created, updated, or deleted)
- Can be used as dependencies by other resources
- Are refreshed during state refresh operations
- Represent external resources (e.g., projects created via Console)
Learn more: Resources Guide