Development Guide

Complete guide for developers who want to contribute to LDAP Manager.

Technology Stack

Frontend

Backend

Testing

Backend Test Suite

Project Structure

ldap-manager/
├── backend/
│   ├── app/
│   │   ├── api/              # API endpoints
│   │   │   ├── entries.py    # LDAP entries endpoints
│   │   │   ├── monitoring.py # Health monitoring
│   │   │   └── connection.py # Connection management
│   │   ├── core/             # Core functionality
│   │   │   ├── ldap_client.py # LDAP operations
│   │   │   └── config.py     # Configuration loader
│   │   ├── models/           # Data models
│   │   └── main.py           # FastAPI application
│   └── requirements.txt      # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── Dashboard.tsx
│   │   │   ├── ClusterDetails.tsx
│   │   │   ├── DirectoryTable.tsx
│   │   │   ├── CreateUserDialog.tsx
│   │   │   ├── EditUserDialog.tsx
│   │   │   ├── MonitoringView.tsx
│   │   │   └── ReplicationTopology.tsx
│   │   ├── lib/              # Utilities
│   │   ├── services/         # API services
│   │   ├── App.tsx           # Main app component
│   │   └── main.tsx          # Entry point
│   ├── tests/                # E2E tests
│   └── package.json          # Node dependencies
├── docs/                     # Documentation
├── config.yml                # Cluster configuration
├── docker-compose.yml        # Docker setup
├── Dockerfile                # Container image
└── README.md                 # Project readme

Local Development Setup

Prerequisites

1. Clone Repository

git clone https://github.com/VibhuviOiO/ldap-manager.git
cd ldap-manager

2. Backend Setup

# Create virtual environment
cd backend
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run backend server
uvicorn app.main:app --reload --port 8000

Backend will be available at http://localhost:8000

3. Frontend Setup

# Install dependencies
cd frontend
npm install

# Run development server
npm run dev

Frontend will be available at http://localhost:5173

4. Configuration

Create config.yml in the root directory:

clusters:
  - name: "Development LDAP"
    host: "localhost"
    port: 389
    bind_dn: "cn=Manager,dc=example,dc=com"
    base_dn: "dc=example,dc=com"

Running Tests

Backend Tests

# Install test dependencies
cd backend
pip install -r requirements-test.txt

# Run all tests with coverage
pytest --cov=app --cov-report=html --cov-report=term-missing

# Run specific test file
pytest tests/test_password_cache.py -v

# Run tests by category
pytest -m security  # Security tests only

View coverage report: open htmlcov/index.html

Test Categories

Frontend E2E Tests

cd frontend
npm run test           # Vitest unit tests
npx playwright test    # E2E tests (all browsers)
npx playwright test --headed  # Watch tests run

Architecture

Frontend Architecture

Browser
   ↓
React App (Port 5173)
   ↓
Services Layer (ClusterService, EntryService, etc.)
   ↓
IHttpClient Interface (SOLID: Dependency Inversion)
   ↓
AxiosHttpClient Implementation
   ↓
Backend API (Port 8000)
   ↓
python-ldap
   ↓
OpenLDAP Server

Component Hierarchy

App.tsx
├── Dashboard.tsx
│   └── ClusterCard (for each cluster)
└── ClusterDetails.tsx
    ├── DirectoryTable.tsx
    │   ├── CreateUserDialog.tsx
    │   ├── EditUserDialog.tsx
    │   └── ColumnSettings.tsx
    ├── MonitoringView.tsx
    │   ├── DirectoryStats.tsx
    │   ├── NodeSyncStats.tsx
    │   └── ReplicationTopology.tsx
    └── ActivityLogView.tsx

API Flow

Frontend Request
   ↓
/api/entries/search
   ↓
FastAPI Endpoint
   ↓
LDAP Client
   ↓
ldapsearch with pagination
   ↓
Parse Results
   ↓
JSON Response

Key Components

Dashboard.tsx

Main landing page showing all configured clusters with health status.

ClusterDetails.tsx

Cluster view with tabs: Users, Groups, OUs, All, Monitoring, Activity.

DirectoryTable.tsx

Reusable table component with search, pagination, and column customization.

CreateUserDialog.tsx

Dynamic form for creating users based on config.yml user_creation_form.

MonitoringView.tsx

Health monitoring dashboard with stats and replication topology.

ReplicationTopology.tsx

Visual representation of multi-master replication using SVG.

Development Workflow

1. Create Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes

3. Run Tests

cd frontend
npm run test:e2e

4. Commit Changes

git add .
git commit -m "feat: add new feature"

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Code Style Guidelines

TypeScript/React

Python/FastAPI

Example: Good Component

interface UserTableProps {
  entries: LDAPEntry[];
  onEdit: (dn: string) => void;
  onDelete: (dn: string) => void;
}

export function UserTable({ entries, onEdit, onDelete }: UserTableProps) {
  return (
    <table>
      {entries.map(entry => (
        <tr key={entry.dn}>
          <td>{entry.uid}</td>
          <td>{entry.cn}</td>
        </tr>
      ))}
    </table>
  );
}

Adding New Features

Adding a New API Endpoint

  1. Create endpoint in backend/app/api/
  2. Add LDAP operation in backend/app/core/ldap_client.py
  3. Create frontend service in frontend/src/services/
  4. Add UI component in frontend/src/components/
  5. Write tests in frontend/tests/e2e/

Adding a New UI Component

  1. Create component file in frontend/src/components/
  2. Define TypeScript interfaces
  3. Use shadcn/ui components
  4. Add to parent component
  5. Test in browser

Building for Production

Build Docker Image

docker build -t ldap-manager:latest .

Test Production Build

docker run -d \
  -p 5173:5173 \
  -p 8000:8000 \
  -v ./config.yml:/app/config.yml \
  ldap-manager:latest

Contributing Guidelines

Before Submitting PR

PR Description Template

## What does this PR do?
Brief description of changes

## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How was this tested?

## Screenshots (if applicable)
Add screenshots for UI changes

Getting Help

Resources

Next Steps