corrad-bp/docs/overview/DEVELOPMENT_GUIDE.md

Development Guide

This guide is intended for developers who are new to the Corrad ProcessMaker project. It covers the setup process, coding conventions, and tips for working with the major components of the system.

Development Setup

Prerequisites

• Node.js (v16+)
• MySQL/MariaDB database
• Git
• Yarn (recommended) or npm

Local Development Environment

1. Clone the repository

   git clone [repository-url]
   cd corrad-processmaker
   

2. Install dependencies

   yarn install
   

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your database connection details
   

4. Generate Prisma client

   npx prisma generate
   

5. Start the development server

   yarn dev
   

6. Access the application Open your browser and navigate to http://localhost:3000

Project Structure

The project follows a standard Nuxt 3 directory structure with some additional folders:

├── assets/              # Static assets (SCSS, images)
├── components/          # Vue components
│   ├── process-flow/    # Process Builder components
│   ├── formkit/         # Custom FormKit components
│   └── rs-*/            # Rose UI components
├── composables/         # Reusable Vue composables
├── doc/                 # Documentation
├── layouts/             # Page layouts
├── middleware/          # Nuxt middleware
├── pages/               # Routes and pages
├── plugins/             # Vue plugins
├── prisma/              # Database schema and migrations
├── public/              # Public static files
├── server/              # API routes and server middleware
└── stores/              # Pinia stores

Naming Conventions

• Components: Use PascalCase for component names (e.g., ProcessFlowCanvas.vue)
• Files: Use kebab-case for filenames (e.g., process-builder.js)
• Custom Rose UI components: Prefix with Rs (e.g., RsButton.vue)
• FormKit custom components: Use PascalCase (e.g., DateTimePicker.vue)
• Stores: Use camelCase (e.g., processBuilder.js)
• API routes: Use kebab-case (e.g., /api/forms/get-all)

Coding Standards

Vue Components

• Use the Composition API with <script setup> for new components
• Define props using defineProps() with proper types
• Use emits with defineEmits()
• Keep components focused on a single responsibility
• Extract reusable logic to composables

<script setup>
// Good example
const props = defineProps({
  nodeId: {
    type: String,
    required: true
  },
  nodeType: {
    type: String,
    default: 'task'
  }
});

const emit = defineEmits(['update', 'delete']);

// Component logic
</script>

CSS Guidelines

• Use Tailwind CSS utility classes when possible
• For custom styles, use SCSS with scoped styles
• Follow the BEM naming convention for custom CSS classes
• Maintain a consistent color scheme using Tailwind's theme colors

State Management

• Use Pinia stores for shared state
• Define clear actions, getters, and state
• Use state composition for complex stores
• Document store functions

Working with Key Components

Process Builder

The Process Builder uses Vue Flow for visualization and consists of several components:

• ProcessFlowCanvas.vue: Main canvas component
• ProcessFlowNodes.js: Node type definitions
• GatewayConditionManager.vue: Manages gateway conditions
• VariableManager.vue: Manages process variables

To add a new node type:

1. Define the node type in ProcessFlowNodes.js
2. Add it to the component palette in ProcessBuilderComponents.vue
3. Update the node properties panel in the Process Builder page
4. Add any necessary handlers in the store

Form Builder

The Form Builder uses FormKit and consists of these main components:

• FormBuilderCanvas.vue: Main canvas for form layout
• FormBuilderComponents.vue: Component library/palette
• FormBuilderConfiguration.vue: Component property editor
• ComponentPreview.vue: Live preview of forms

To add a new form component:

1. Add the component definition to the component library
2. Add configuration options to the configuration panel
3. Update the FormKit component if necessary
4. Add any special rendering logic to the preview component

API Integration

The backend API is built with Nitro.js and follows RESTful conventions:

• API routes are defined in the server/api/ directory
• Route handlers use Prisma for database operations
• Authentication is handled via middleware

Example API route:

// server/api/forms/index.js
export default defineEventHandler(async (event) => {
  // Get query parameters
  const query = getQuery(event);
  
  // Get forms from database
  const forms = await prisma.form.findMany({
    where: {
      status: 'active'
    },
    orderBy: {
      createdDate: 'desc'
    }
  });
  
  return forms;
});

Testing

TODO: Add testing guidelines once testing is implemented.

Deployment

For production deployment:

1. Build the application:

   yarn build
   

2. Start the production server:

   yarn start
   

Alternatively, you can use PM2 for process management:

pm2 start ecosystem.config.js

Getting Help

• Check the existing documentation in the doc/ directory
• Read the codebase, particularly the main components
• Ask for help from other team members
• Consult the Nuxt, Vue, and FormKit documentation for framework-specific questions

---

Remember that this is a complex application. Take time to understand how the components interact before making significant changes.