dfat-lambda-api

The dfat-lambda-api repository is a backend solution template, used by the dfat CLI, that can be added to a standalone Flutter app to make it a cloud-hosted Flutter app.

The Paradigm

The dfat paradigm is that you should focus on your app, the experience, the users, and not the infrastructure. DFAT aims to enable you to build a local prototype, install an appropriate backend and immediately start using it via an API accessible in the frontend.

The objective, and primary use case, is a standalone Flutter app (new or existing) should be able to run two (2) commands and have a deployable backend, fully tested and ready for customization.

The two commands are:

dart pub global activate dfat
dfat install lambda-api

System Requirements

The following tools chain is required for dfat. It will not install any of these tools for you. It will check if the tools and folders it needs are present on your system and in your workspace by using the dfat check command.

Required Tools

• Dart
• Docker
• Flutter
• Git
• Terraform

Using dfat check

The command is simple: dfat check. The output is also simple, here's an example:

❯ dfat check
🤖 Processing 'Check'
   🔦 Looking for dart..............................✅
   🔦 Looking for docker............................✅
   🔦 Looking for flutter...........................✅
   🔦 Looking for git...............................✅
   🔦 Looking for terraform.........................✅
   🔦 Looking for .dfat.............................✅
   🔦 Looking for iac...............................✅
   🔦 Looking for lambdas...........................✅
   🔦 Looking for schemas...........................✅
   🔦 Looking for shared............................✅
   🔦 Looking for assets............................✅
🏁 Finished 'Check'

If any of the tools or folders were not found, the green box with a white check (✅) would be replaced with a yellow orb (🟡), and a message indicating if this is auto-repairable or not. Here's an example:

❯ dfat check
🤖 Processing 'Check'
   🔦 Looking for dart..............................✅
   🔦 Looking for docker............................✅
   🔦 Looking for git...............................✅
   🔦 Looking for .dfat.............................🟡 missing, can re-create.
   🔦 Looking for iac...............................🟡 missing, won't re-create.
   🔦 Looking for lambdas...........................✅
   🔦 Looking for schemas...........................🟡 missing, can re-create.
   🔦 Looking for shared............................✅
   🔦 Looking for assets............................✅
   🟡 One or more folders doesn't exist. Running `dfat check --fix` might fix this.
🏁 Finished 'Check'

As indicated by the note, running dfat check --fix can fix some of these problems in your workspace. The ones it won't fix are because it might clobber your customizations if it tried.

¯\(ツ)/¯

What's Here?

Thanks for asking! Let's take a look at the solution folder structure and why we have each part. We'll only discuss the aspects introduced by dfat and won't cover the other app / dart / Flutter specific files.

Folders

💫 Generated with https://tree.nathanfriend.io

workspace/
├── .dfat/
│   ├── schemas/
│   │   ├── iac.lambda.schema.json
│   │   └── iac.shared.schema.json
│   ├── Dockerfile.dfat.al2
│   └── run.sh
├── iac/
│   ├── iac.auto.tfvars.json
│   ├── main.tf
│   └── variables.tf
├── lambdas/
│   ├── meta/
│   │   ├── .dist
│   │   └── iac.json
│   └── todo/
│       ├── .dist
│       └── iac.json
└── shared/
    ├── assets/
    │   ├── cognito_logo.png
    │   ├── cognito_logo.psd
    │   └── cognito_styles.css
    ├── lib/
    │   ├── src/
    │   │   ├── backend/
    │   │   │   ├── requests
    │   │   │   └── handler.dart
    │   │   ├── clients
    │   │   ├── common/
    │   │   │   └── extensions
    │   │   ├── contracts/
    │   │   │   └── messages
    │   │   └── frontend/
    │   │       ├── requests
    │   │       ├── api.dart
    │   │       └── http_api_provider.dart
    │   ├── client.dart
    │   └── server.dart
    └── iac.json

• workspace → This is your project root
  • .dfat → Holds critical files for normal dfat operations
    • schemas → The JSON schemas for IaC files
      • iac.lambda.schema.json → Defines the deployment options (routes, timeouts, memory, etc.) schema per lambda
      • iac.shared.schema.json → Defines the deployment options (URL, stages, IPDs, user attributes, etc) schema for the backend
    • Dockerfile.dfat.al2 → An Amazon Linux 2 docker image definition for building the lambdas in their target runtime
    • run.sh → Installs and runs dfat in the docker image
  • app → Where your Flutter app lives in relation to the rest of the solution
  • iac → The Terraform IaC (infrastructure as code) definition for backend deployment
    • iac.auto.tfvars.json → This file only exists after dfat build or, more precisely, after dfat aggregate (one of the first build steps)
    • main.tf → Defines your AWS backend, state configuration, and references the dfat terraform-aws-lambda-api module
    • variables.tf → All the variables required by the module, these are ALL mapped from the iac.auto.tfvars.json file
  • lambdas → The top-level container folder for your lambda function implementations
    • meta → An example meta lambda function that returns Amazon Cost Explorer data for your account, and can be filtered by tags.
      • .dist → An intermediate folder used by dfat to stage the native build output for ZIP compression and aggregation
      • iac.json → The deployment options for this lambda see: iac.lambda.schema.json
    • todo → An example todo lambda function that implements the CRUD operations for Todo Items
      • Otherwise, same files, folders and intentions at meta
• shared → The shared library between the lambdas and the app. While you cannot change the folder names, you can change all of the package names to whatever you want. Reference the client.dart barrel from shared in your app, the lambdas reference the server.dart barrel for their functionality
  • assets → Non-code assets used in the deployment. RIght now, these are primarily Amazon Cognito Client Application Hosted UI customization file.
    • cognito_logo.png → A rendered logo for the Cognito Hosted UI
    • cognito_logo.psd → The layered source logo for the Cognito Hosted UI
    • cognito_styles.css → A copy of the official, default style sheet for customizing the Cognito Hosted UI
  • lib
    • src
      • backend → The backend focal point for the shared library
        • requests → The backend version of the request models, optimized for the backend needs
        • handler.dart → The backend primary interaction point. A lambda shouldn't call much of anything except this
      • clients → Client implementations to databases and other systems, typically these are only used by the handler
      • common → Commonly available and accessible functionality (extensions, UI fakes, etc.) for both frontend and backend
      • contracts → As the name suggests, these are the contract between frontend and backend. These are meant to be serializable and simple. More complete and specific version are available in the frontend and backend as request implementations
        • messages → While the contracts are the shape of your data in both sides of the wire, the messages are the request and response types using those shapes for various operations. Like contracts, these must be serializable and not contain anything frontend nor backend specific
      • frontend → The frontend focal point for the shared library
        • request → The frontend version of the request models, optimized for the frontend needs
        • api.dart → The frontend primary interaction point. A frontend shouldn't call a backend except through this
        • http_api_provider.dart → A request object mixin that locks the response type with type arguments and facilitates the serialization, HTTP call, and deserialization of the response. This is where you might want to handle additional headers, tracing, or other network operations/modifications
  • iac.json → The general deployment options for this backend. See: iac.shared.schema.json