d176e40726
# refactor: restructure .cursor directory for improved organization and clarity ## Description This PR refactors the `.cursor` directory to enhance organization, clarity, and maintainability. ### Problem The existing `.cursor` directory lacked clear organization, making it difficult to find specific files, understand their purpose, and add new components consistently. ### Solution A comprehensive restructuring: #### New Directory Structure ``` .cursor/ ├── settings.json # Main configuration file ├── docs/ # Documentation │ ├── guides/ # In-depth guides │ ├── references/ # Quick references │ └── practices/ # Best practices ├── rules/ # Rule definitions │ ├── commit/ # Commit-related rules │ ├── quality/ # Code quality rules │ ├── testing/ # Testing rules │ └── verification/ # Verification rules └── hooks/ # Git hooks and scripts ``` #### Key Changes 1. **Logical Categorization**: Organized files into clear categories based on purpose 2. **Improved Documentation**: Added comprehensive README files for each directory 3. **Standardized Naming**: Implemented consistent kebab-case naming convention 4. **Reference Updates**: Updated all internal references to point to new file locations ### Benefits - **Easier Navigation**: Clear categorization makes finding files intuitive - **Improved Understanding**: Comprehensive documentation explains purpose and usage - **Simplified Maintenance**: Logical structure makes updates and additions easier - **Better Onboarding**: New team members can quickly understand the system This refactoring sets a solid foundation for all Cursor AI-related configurations and rules, making it easier for the team to leverage Cursor's capabilities.
226 lines
7.0 KiB
Markdown
226 lines
7.0 KiB
Markdown
# 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. |