NEBULA Frontend Platform

Overview

NEBULA is a modern web application built with React, TypeScript, and Vite, following Domain-Driven Design (DDD) principles. The platform provides a comprehensive UI component library and implements best practices for frontend development.

Table of Contents

1. Architecture Overview
2. Project Structure
3. Technology Stack
4. Getting Started
5. Development Workflow
6. Component Library
7. Domain Structure
8. Available Scripts
9. Project Configuration
10. Contributing Guidelines

Architecture Overview

The application follows Domain-Driven Design (DDD) principles, organizing code around business domains rather than technical layers. This approach provides:

• Clear separation of concerns
• Domain-specific components and logic
• Scalable and maintainable codebase
• Isolated domain dependencies
• Reusable shared components

Technology Stack

Core Technologies

• React (Version 18)
• Vite
• React Query (Version 4)
• React Hook Form (Version 7) + Zod
• Zustand
• React Router Dom (Version 6)

UI & styling

• Tailwindcss
• Radix-UI
• Shadcn

Static type checking & linting

• Typescript
• Husky
• Commitlint

Testing Libraries

• Vitest
• @testing-library/react
• @testing-library/dom
• @testing-library/jest-dom
• @testing-library/user-event

ESLint + Prettier

• Eslint
• Prettier
• eslint-config-prettier
• eslint-plugin-prettier
• prettier-plugin-tailwindcss
• @ianvs/prettier-plugin-sort-imports

Others

• class-variance-authority

1. Install the “Tailwind CSS IntelliSense” Visual Studio Code extension
2. Add the following to your settings.json(opens in a new tab):

{
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

• Storybook
• Mantine Dates
• React-number-format
• React-select

Getting Started

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Docker (for containerization)

Environment Setup

1. Clone the repository:

git clone <repository-url>
cd nebula-frontend

2. Create environment file:

cp .env.example .env

3. Install dependencies:

npm install

4. Start development server:

npm run dev

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run test - Run unit tests
• npm run storybook - Start Storybook server
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run commit - Interactive commit message helper

Docker Support

# Build Docker image
docker build -t nebula-frontend .

# Run container
docker run -p 3000:3000 nebula-frontend

Development Workflow

Source Version Control

• Trunk-based development

Git branch naming convention:

• New feature: feat/NEB-{Ticker Number}_{Ticker Name}
• Fix bug: fix/NEB-{Ticker Number}_{Ticker Name}
• Chore: chore/NEB-{Ticker Number}_{Ticker Name}

Example: feat/NEB-229_integrate_api_add_new_internal_users

Git commit message convention:

• New feature: git commit -m “feat: [NEB-{Ticker Number}] message”
• Fix bug: git commit -m “fix: [NEB-{Ticker Number}] message”
• Chore: git commit -m “chore: [NEB-{Ticker Number}] message”

Example: git commit -m "feat: [NEB-229] integrate api add new internal users"

Gitflow

• git add .
• npm run commit
• git fetch
• git rebase origin/main
• git push —set-upstream origin {Name branch}

Coding Convention

• All variables named as const or enum should be in UPPERCASE according to naming conventions.

const COLOR = '#FF0000';
enum DAYS {
  MONDAY,
  TUESDAY,
  WEDNESDAY,
}

• Types and Interfaces should be in CapitalizedCamelCase.

interface PersonDetails {
  firstName: string;
  lastName: string;
  age: number;
}

type ProductInfo = {
  name: string;
  price: number;
};

• Using path aliases for cleaner React and TypeScript imports.

import Button from '@/components/NEBButton';
import Input from '@/components/NEBInput';

• File Naming Conventions, all files and folders should be named in kebab-case.

Reference Material

• Common mistakes with React Testing Library
• Coding Style

Project Structure

The project follows a Domain-Driven Design (DDD) architecture with the following structure:

src/
├── assets/              # Static assets (images, fonts)
├── components/          # Shared UI components
├── domains/            # Domain-specific modules
│   ├── authentication/  # Authentication domain
│   │   ├── components/  # Domain-specific components
│   │   ├── pages/      # Route components
│   │   ├── hooks/      # Custom hooks
│   │   ├── services/   # API services
│   │   ├── types/      # TypeScript definitions
│   │   └── utils/      # Helper functions
│   └── [other-domains]/
├── hooks/              # Shared hooks
├── services/           # Shared API services
├── libs/               # Third-party integrations
├── router/             # Route definitions
├── store/              # Global state management
├── types/              # Shared TypeScript types
└── utils/              # Shared utilities

Domain Structure

Each domain follows a consistent structure:

• components/: Domain-specific UI components
• pages/: Route components and layouts
• hooks/: Custom React hooks
• services/: API integration and business logic
• types/: TypeScript interfaces and types
• utils/: Helper functions and utilities

Component Library

The project uses a comprehensive UI component library built with:

• Storybook for component documentation
• Tailwind CSS for styling
• Radix UI for accessible components
• Shadcn UI for prebuilt components
• Class Variance Authority for component variants

Component Development

1. Create new components in src/components
2. Add Storybook documentation
3. Include unit tests
4. Follow accessibility guidelines

Project Configuration

Tools and Linting

• ESLint for code linting
• Prettier for code formatting
• Husky for git hooks
• Commitlint for commit message validation

CI/CD

The project uses Bitbucket Pipelines for continuous integration and deployment:

• Automated testing
• Code quality checks
• Build verification
• Deployment to staging/production

Contributing

1. Create a new branch following the naming convention:

• Features: feat/NEB-{Ticket}-description
• Fixes: fix/NEB-{Ticket}-description
• Chores: chore/NEB-{Ticket}-description

2. Make your changes following the coding standards

3. Commit using conventional commits:

npm run commit

4. Push and create a pull request

Support

For support and questions, please contact the development team.