PromucFlow_constructor/.cursor/docs/references/codebase-map.md

# Appsmith Codebase Map

This document provides a comprehensive overview of the Appsmith codebase structure to help Cursor AI better understand the organization and relationships between different components.

## Project Overview

Appsmith is a low-code platform that allows developers to build internal tools and dashboards by connecting to databases, APIs, and other data sources. The application consists of:

1. A React-based frontend (client)
2. A Java Spring Boot backend (server)
3. Various plugins for connecting to external data sources
4. A self-contained deployment architecture

## Directory Structure

The codebase is organized into the following main directories:

- `app/` - Contains the main application code
  - `client/` - Frontend application (React)
  - `server/` - Backend application (Java Spring Boot)
  - `util/` - Shared utilities
  - `monitoring/` - Monitoring and metrics

## Frontend Architecture (app/client)

The frontend is built with React, Redux, and TypeScript. Key directories include:

### Core Structure (app/client/src)
- `actions/` - Redux actions
- `reducers/` - Redux reducers
- `sagas/` - Redux sagas for side effects and async operations
- `selectors/` - Redux selectors
- `store.ts` - Redux store configuration

### UI Components
- `components/` - Reusable UI components
- `pages/` - Page-level components
- `widgets/` - Draggable widgets for the page builder
- `theme/` - Styling and theme definitions
- `icons/` - SVG icons and icon components

### Data and APIs
- `api/` - API client and service functions
- `constants/` - Application constants and configuration
- `utils/` - Utility functions
- `entities/` - Data models and entity definitions

### Edition-specific Code
- `ee/` - Enterprise Edition specific code
- `ce/` - Community Edition specific code

### Testing
- `test/` - Test utilities and mocks
- `cypress/` - End-to-end testing with Cypress

## Backend Architecture (app/server)

The backend is built with Java Spring Boot and MongoDB. Key packages include:

### Core Structure (app/server/appsmith-server/src/main/java/com/appsmith/server)
- `ServerApplication.java` - Main application entry point

### API Layer
- `controllers/` - REST API controllers
- `dtos/` - Data Transfer Objects
- `exceptions/` - Custom exception classes

### Business Logic
- `services/` - Business logic and service implementations
- `helpers/` - Helper classes and utilities
- `domains/` - Domain models

### Data Access
- `repositories/` - Data access repositories
- `configurations/` - Database and application configuration

### Features
- `applications/` - Application management
- `pages/` - Page management
- `actions/` - Action management (API, DB queries)
- `plugins/` - Plugin system for external integrations
- `datasources/` - Data source management
- `authentication/` - Authentication and authorization
- `organization/` - Organization management

### Extensions
- `appsmith-plugins/` - Plugin implementations
- `appsmith-git/` - Git integration features
- `appsmith-interfaces/` - Core interfaces
- `appsmith-ai/` - AI features implementation

## Key Concepts

### Frontend Concepts

1. **Widgets**: Draggable UI components that users can place on their pages
2. **Actions**: API calls, DB queries, or JS code that widgets can trigger
3. **Datasources**: Connections to external data sources like databases or APIs
4. **Pages**: Containers for widgets representing different views in an application
5. **Theme**: Visual styling applied to the entire application

### Backend Concepts

1. **Applications**: Container for pages and other resources
2. **Organizations**: Groups of users and applications
3. **Plugins**: Connectors to external services
4. **Actions**: Executable code blocks (API calls, DB queries)
5. **Datasources**: Connection configurations for external data systems

## Code Patterns

### Frontend Patterns

1. **Redux for State Management**:
   - Actions define state changes
   - Reducers implement state updates
   - Sagas handle side effects
   - Selectors extract state

2. **Component Structure**:
   - Functional components with hooks
   - Container/Presentation separation
   - Styled-components for styling
   - Typescript interfaces for type safety

3. **API Communication**:
   - Axios-based API clients
   - Redux sagas for async operations
   - Error handling middleware

### Backend Patterns

1. **Spring Boot Architecture**:
   - Controller -> Service -> Repository pattern
   - DTO pattern for API requests/responses
   - Reactive programming with Reactor

2. **Security**:
   - JWT-based authentication
   - RBAC (Role-Based Access Control)
   - Permission checks with Spring Security

3. **Database**:
   - MongoDB as primary datastore
   - Reactive repositories

## Common Workflows

### Frontend Development Workflow

1. Define Redux actions in `actions/`
2. Implement reducers in `reducers/`
3. Create sagas for async operations in `sagas/`
4. Build UI components in `components/` or `pages/`
5. Connect components to Redux using selectors

### Backend Development Workflow

1. Define DTOs in `dtos/`
2. Create domain models in `domains/`
3. Implement repositories in `repositories/`
4. Add business logic in `services/`
5. Expose APIs in `controllers/`

## Testing Approach

### Frontend Testing
- Unit tests with Jest and React Testing Library
- End-to-end tests with Cypress
- Visual regression tests

### Backend Testing
- Unit tests with JUnit
- Integration tests with Spring Boot Test
- API tests with RestAssured

## Performance Considerations

### Frontend Performance
- Memoization of heavy computations
- Code splitting for page loads
- Virtualization for large lists
- Optimized rendering with React.memo

### Backend Performance
- Query optimization in MongoDB
- Caching strategies
- Reactive programming for non-blocking operations

## Security Model

1. **Authentication**: JWT-based auth with refresh tokens
2. **Authorization**: RBAC with granular permissions
3. **Data Isolation**: Multi-tenancy support

## Enterprise vs Community Edition

The codebase is separated into:
- `ee/` - Enterprise features
- `ce/` - Community features

Key differences:
1. Enterprise: SSO, audit logs, role-based access
2. Community: Basic features, self-hosted option

## Important Files

### Frontend
- `client/src/index.tsx` - Application entry point
- `client/src/store.ts` - Redux store configuration
- `client/src/App.tsx` - Main application component

### Backend
- `server/appsmith-server/src/main/java/com/appsmith/server/ServerApplication.java` - Main entry point
- `server/appsmith-server/src/main/resources/application.yml` - Application configuration

## Development Guidelines

1. Follow the established patterns in the existing codebase
2. Use TypeScript interfaces for type safety in frontend
3. Add appropriate tests for all new features
4. Document complex logic with comments
5. Use reactive programming patterns in backend
6. Follow established file naming conventions

This map should help Cursor better understand the Appsmith codebase structure and provide more contextual assistance when working with the code.