Projects in Suga are application specifications that define your cloud architecture using abstract resource types. They’re declarative YAML configurations that describe what your application needs - services, storage, databases, and networking - without being tied to specific cloud implementations.

​
What is a Project?

A Suga project is defined by a suga.yaml file that describes your application’s infrastructure requirements using cloud-agnostic resource types. When combined with a Platform, this specification gets transformed into deployable cloud infrastructure.

​
Project Structure

​
Basic Configuration

Every project starts with basic metadata and target platforms:
Basic project configuration
name: project-name
description: Brief description of your application

targets:
  - suga/aws@1 # Deploy to AWS
  - suga/gcp@1 # Or deploy to GCP
  • name: Project identifier (used in Terraform stack and resource naming)
  • description: Human-readable project description
  • targets: List of platforms this project can use for deployments

​
Resource Types

Projects currently offer four main resource types:
  • Services - Application containers that handle business logic
  • Buckets - Cloud storage for files, images, and other assets
  • Entrypoints - HTTP routing and CDN configuration to expose your application
  • Databases - Persistent data storage with access controls (currently PostgreSQL only)

​
Services

Services are your application containers that handle business logic:
Service definitions
services:
  app:
    env:
      EXT_URL: https://somewhere.example.com
    container:
      docker:
        dockerfile: Dockerfile
        context: .
    dev:
      script: npm run dev

  worker:
    container:
      image:
        id: "my-registry/worker:latest"
Services support:
  • Environment variables for configuration
  • Container definitions (Dockerfile or pre-built images)
  • Development scripts for local testing with the suga dev CLI command

​
Buckets

Buckets provide cloud storage for files, images, and other assets:
Bucket definitions
buckets:
  uploads:
    access:
      app:
        - read
        - write
        - delete

  public-assets:
    content_path: ./build-static
    access:
      app:
        - read
Bucket access permissions define which services can read, write or delete files in the bucket. Buckets can optionally include a content_path which, if provided, is used to seed the bucket with files during deployments. This is useful when you want to deploy static website assets, then route to them via an entrypoint.

​
Entrypoints

Entrypoints expose your application to the internet, typically through CDNs and/or load balancers:
Entrypoint definitions
entrypoints:
  web:
    routes:
      /:
        name: public-assets
      /api/:
        name: app
Routes map URL patterns to services or storage buckets.

​
Databases

Databases provide persistent SQL data storage (currently PostgreSQL only):
Database definitions
databases:
  main:
    access:
      app:
        - query
Database access controls which services can access and query the database.

​
Project Benefits

​
Deployment-Agnostic Architecture

Projects describe what your application needs, not how it’s implemented:
  • Portable designs that work across different cloud providers
  • Platform independence - switch from one AWS service to another, or to another cloud like GCP without changing your project
  • Future-proof architecture that adapts as platforms evolve

​
Developer Experience

Projects enable smooth local development and deployment workflows:
  • Local emulation - Test with emulated cloud services on your machine using suga dev
  • Hot reloading - Services restart automatically when code changes
  • Environment parity - Same resource relationships locally and in production

​
Platform Team Control

Projects maintain separation between application architecture and infrastructure implementation:
  • Governance enforcement - Platform teams control how resources get deployed
  • Security policies - Access patterns and configurations managed at the platform level
  • Operational consistency - Standardized deployment and monitoring across teams

​
Project Lifecycle

​
1. Design Phase

Define your application architecture using the visual editor suga edit or by editing suga.yaml directly:
  • Drag and drop resources onto the canvas
  • Connect services to storage and databases
  • Configure access permissions and routing
  • Set environment variables and deployment options

​
2. Development Phase

Test your project locally with emulated cloud services: 
suga dev
  • Services run using your dev.script commands
  • Storage operations use local filesystem
  • Database connections point to local instances
  • HTTP requests route through local entrypoints

​
3. Build Phase

Generate cloud-specific infrastructure from your project: 
suga build
  • Suga combines your project with the target platform specifications
  • Terraform stacks are generated for your target platform using pre-built modules
  • Resource dependencies and networking get configured automatically

​
4. Deploy Phase

Deploy the generated infrastructure using Terraform: 
cd .suga/stacks/my-app-aws-*
terraform init
terraform apply