ZoopFlow Project Structure

This guide explains the recommended project structure for ZoopFlow applications.

Directory Structure

The following is a typical directory structure for a ZoopFlow application:

Directory Explanation

src

The src directory contains all the source code for your ZoopFlow application.

steps

The steps directory contains all the step definitions, organized by domain or feature:

// src/steps/user-management/create-user.ts
import { defineStep } from '@zoopflow/core';
 
export const createUser = defineStep({
  id: 'user-management.create-user',
  version: '1.0.0',
  // ... step definition
});

Each domain folder has an index.ts file that exports all steps:

// src/steps/user-management/index.ts
export * from './create-user';
export * from './update-user';
export * from './delete-user';

The top-level index.ts exports all step domains:

// src/steps/index.ts
export * from './user-management';
export * from './notifications';

flows

The flows directory contains flow definitions:

// src/flows/user-onboarding-flow.ts
import { defineFlow } from '@zoopflow/core';
import { createUser, sendWelcomeEmail } from '../steps';
 
export const userOnboardingFlow = defineFlow({
  id: 'flows.user-onboarding',
  version: '1.0.0',
  // ... flow definition
});

schemas

The schemas directory contains ZSchema definitions:

// src/schemas/user-schemas.ts
import { defineZSchema, ZSchemaTag } from '@zoopflow/core/zschema';
 
export const UserSchema = defineZSchema({
  name: 'User',
  tags: [ZSchemaTag.PII],
  // ... schema definition
});

services

The services directory contains service integrations:

// src/services/email-service.ts
export class EmailService {
  async sendEmail(to, subject, body) {
    // Implementation
  }
}

utils

The utils directory contains utility functions:

// src/utils/validation.ts
export function isValidEmail(email) {
  // Implementation
}

tests

The tests directory contains test files, organized to mirror the structure of the src directory.

Best Practices

1. Domain-Driven Structure: Organize steps and flows by domain or business capability
2. Index Files: Use index files to simplify imports
3. Consistent Naming: Use consistent naming conventions for files and exports
4. Step/Flow Separation: Keep steps and flows in separate directories
5. Schema Organization: Group related schemas together
6. Test Mirroring: Mirror the source directory structure in the test directory

Monorepo Structure

For larger applications, a monorepo structure may be appropriate:

This structure allows for better separation of concerns and independent versioning of components.