Our platform follows a hierarchical structure designed to provide secure, organized access to various resources and automation capabilities. Understanding these core components and their relationships will help you build more effective data import solutions.

​
Platform Architecture

Flatfile operates as a hosted platform that integrates with your application through APIs and SDKs. Your users interact with Flatfile’s interface while you maintain control over the data flow and business logic through event-driven listeners and customizable workflows.

​
Core Concepts

Understanding Flatfile’s architecture starts with these fundamental concepts, organized by their role in the platform:

​
Infrastructure & Organization

Environments provide isolated contexts for development, testing, and production, ensuring secure separation of your data import implementations across different stages.

Apps serve as containers for related Spaces and configurations, helping organize multiple data import workflows within your broader application ecosystem.

Spaces are micro-applications with their own database, filestore, and authentication, serving as the primary container for data import workflows and user interactions.

​
Data Structure

Workbooks function like databases with type-strict Blueprints, replacing traditional spreadsheet templates and providing structured containers for imported data.

Sheets are individual data tables within Workbooks that organize and structure imported data, each representing a distinct data type or entity.

Blueprints define the data structure and field types for your import process, specifying how data should look, behave, and connect.

Fields represent individual data points within Blueprints, each with specific types and configuration options to define data structure.

Records are individual rows of data within Sheets, representing the actual data that users import and transform through your workflows.

​
Automation & Processing

Listeners contain the core logic of your Flatfile implementation, responding to Events with custom data transformations, validations, and integrations.

Plugins extend Flatfile’s capabilities with reusable functionality, offering everything from data transformations to UI enhancements.

Jobs handle long-running operations and background processing, providing progress tracking and status updates for complex data operations.

Actions enable custom user interactions through buttons and triggers, allowing users to initiate specific workflows or operations on their data.

​
Content & Documentation

Documents are standalone webpages within Spaces that provide guidance, instructions, and interactive content to help users navigate their data import process.

​
Validation and Transformations

Flatfile provides several approaches for implementing data validation and transformation logic. For detailed data handling patterns, see our Handling Data guide:

RecordHooks operate on individual records, automatically executing validation and transformation logic every time a record is inserted or updated.

Listener code provides fully-customized validation and transformation capabilities using the Flatfile API. Listeners respond to events like commit:created and record:deleted, and can operate on any number of Records, Sheets, or Blueprints at once.

Actions perform validations and transformations on any number of Records, Sheets, or Blueprints at once when users click an Action button. Actions are fundamentally the same as Listener code, but use a button to emit events rather than reacting to platform-generated events.