Skip to content

Onboarding

Jump to bottom
Rudoi Dmytro edited this page Dec 16, 2025 · 19 revisions

Welcome to VilnaCRM!

We’re excited to have you join us as a new front-end contributor. This document will help you set up your development environment, understand our project architecture and tech stack, and familiarize yourself with our coding standards and processes.

VilnaCRM is an open-source CRM system developed by a Ukrainian team to automate sales for small and medium-sized businesses. The landing page's primary audience includes business owners and sales managers, while the CRM system targets sales departments, accountants, IT specialists, and management teams.

This onboarding document aims to help new interns, trainees, and contributors quickly learn and contribute effectively to our frontend codebase.

Table of Contents

  1. Development Environment & Setup
  2. Project Architecture & Tech Stack
  3. Coding Standards & Best Practices
  4. Testing & QA
  5. Continuous Integration & Deployment
  6. Useful Resources & References
  7. Mentoring & Support
  8. Next Steps

Development Environment & Setup

Operating System Requirements

  • Ubuntu or macOS (Unix-based, CI-tested)
  • Node.js 20 required
  • No Windows/WSL or proprietary tools (not supported)

IDE Recommendations

  • We recommend using WebStorm with AI Assistant or Cursor AI. If you are a student, you can obtain a student license for free.

Also, please install the Coderabbit AI Plugin into your IDE.

Cloning Repositories & Installing Dependencies

  1. Navigate to the VilnaCRM Website repository.
  2. Follow the “Minimal Installation” instructions in the repository’s README.
  3. Once the repository is cloned locally, install dependencies: 
    make install

Version Control Configuration

  • We use Git with a standard branching strategy (e.g., feature branches, main/master as the production branch).
  • Please adhere to our commit message conventions specified in our CONTRIBUTING.md file.

Build & Bundling Tool

  • Next.js compiler is our primary bundler. Familiarity with basic configuration is helpful.

Project Architecture & Tech Stack

Frameworks & Libraries

Folder Structure & Key Components

Our frontend code is loosely based on the principles outlined in bulletproof-react.

Styling Approach

In general, we use MUI. Check the specific repository’s documentation.

Modern JavaScript Stack

  • React + Next.js are our primary tools.
  • We have CI checks to ensure high code quality (security checks, style fixing, static linters, DeepScan, Snyk, and more).
  • Configured testing tools include Playwright and Jest.
  • The template is based on bulletproof-react.

Internal Libraries & Shared Components

We have a shared UI toolkit and other internal libraries. See:

Coding Standards & Best Practices

Style Guidelines

  • We use Next lint, Prettier, Typescript linter and other linters. Always check CI rules and run: 
      make format
  make lint-eslint
  make lint-tsc
  make lint-md
    for instructions on how to fix code style automatically.

Component Organization & Reusability

State Management

  • Currently, we do not use Redux or a centralized state management library. For React, we rely on built-in features like the Context API or local component states as needed.

Security & Performance

  • Always be mindful of lazy loading, code splitting, and other performance optimizations.
  • Handle sensitive data on the server-side where possible; limit client exposure.
  • CI checks in GitHub will flag potential security issues.

Here is a small React component snippet (example of best practices):

import React from 'react';

interface ButtonProps {
  onClick: () => void;
  label: string;
}

export const Button: React.FC<ButtonProps> = ({ onClick, label }) => {
  return (
    <button type="button" onClick={onClick}>
      {label}
    </button>
  );
};

Testing & QA

Testing Tools

  • Jest for unit tests.
  • Playwright for end-to-end (E2E) tests and visual tests.
  • React Testing Library for component testing (where applicable).

Best Practices for Writing Tests

  • Keep tests short, focused, and descriptive.
  • Use descriptive test names (e.g., it('should render the button correctly')).
  • Mock dependencies where necessary to keep tests deterministic.

Running & Interpreting Tests

  • Run your tests locally before pushing any changes: 
    make test-e2e
make test-mutation
make test-visual
make test-unit-all
  • Check the terminal output or CI logs for errors or coverage summaries.

Continuous Integration & Deployment

We use GitHub Actions with a variety of checks (15 CI checks, specifically), including:

  1. e2e testing / test
  2. Format yaml files / yamlfmt
  3. Mutation Testing / mutation-testing
  4. Visual Tests / visual-test
  5. codecov / codecov
  6. generate changelog and create pre release / build
  7. load testing / load-testing
  8. memory leak testing / memory-leak-testing
  9. performance testing / performance
  10. security testing / Analyze (typescript)
  11. static testing / static
  12. unit testing / unit
  13. Sandbox Creation and Rebuild / TriggerRotation
  14. Sandbox Creation and Rebuild / SandboxPipelineExecution
  15. Code scanning results / CodeQL

Additionally, we use:

  • CodeRabbit for code reviews and AI suggestions.
  • Snyk for security scanning.

Deploying Code to Sandbox & Production

  • Sandbox: Create a new branch, open a Pull Request (PR). Once the PR is created, GitHub Actions automatically builds a sandbox and comments with a deployment link.
  • Production: Merge your PR into the main branch. That triggers the production deployment pipeline.

Code Reviews & Approvals

  • All PRs require approval from @kravalg and coderabbit ai before merging.

Useful Resources & References

Recommended Online Courses & Tutorials

Coding Challenge Platforms

Mentoring & Support

If you need help, reach out:

  • Slack is our main communication channel. Join the frontend chat for quick questions and collaboration.
  • You can also schedule 1:1 sessions with your assigned mentor or the Frontend Lead.
  • Key contact: @kravalg (Solutions Architect).

Next Steps

Please read day to day workflow

Congratulations on taking the first step in your VilnaCRM journey

We appreciate your time and effort to learn our processes, and we are here to support you.

Start exploring the repositories, experiment with small fixes or features, and don’t hesitate to ask questions in Slack.

Thank you for joining the VilnaCRM team, and we look forward to building great software together!

Clone this wiki locally