Frontend Documentation

The DBCalm frontend is a modern web application for managing database backups, built with React, TypeScript, and Vite.

Overview

The frontend provides a web-based interface for:

Dashboard: Monitor backup status across all your database servers
Client Management: Add and configure database clients
Backup Scheduling: Create and manage backup schedules with cron expressions
Restore Operations: Point-in-time restore functionality
Process Monitoring: Real-time tracking of backup and restore operations
User Authentication: Secure login and session management

Technology Stack

React 19: Modern UI library
TypeScript: Type-safe development
Vite: Fast build tool with Hot Module Replacement (HMR)
React Router: Client-side routing
Tailwind CSS 4: Utility-first styling framework
DaisyUI: Component library for Tailwind
date-fns: Date manipulation and formatting

Prerequisites

Node.js 18 or higher
npm (comes with Node.js)
Running DBCalm backend API

Installation

Clone the repository:

cd frontend
npm install

Create a .env file in the frontend directory:

VITE_API_URL=https://dbcalm.localhost:8335

# For production, use your actual API URL:
# VITE_API_URL=https://api.yourdomain.com

Local Development

Start the development server:

npm run dev

# Or using Make:
make dev

The application will be available at http://localhost:5173 with hot module replacement enabled.

Development Features:

Hot Module Replacement: Changes reflect instantly without full page reload
TypeScript: Type checking and IntelliSense support
ESLint: Code quality checking with npm run lint
Fast Refresh: React components reload while preserving state

Project Structure

frontend/
├── src/
│   ├── pages/              # Page components
│   │   ├── Dashboard.tsx   # Main dashboard
│   │   ├── Clients.tsx     # Client list
│   │   ├── AddClient.tsx   # Add new client
│   │   ├── Schedules.tsx   # Backup schedules
│   │   ├── ScheduleForm.tsx # Create/edit schedule
│   │   ├── Restores.tsx    # Restore operations
│   │   ├── Processes.tsx   # Process monitoring
│   │   └── Login.tsx       # Authentication
│   ├── components/         # Reusable components
│   │   ├── Header.tsx
│   │   ├── Pagination.tsx
│   │   ├── Toast.tsx
│   │   └── ...
│   ├── hooks/              # Custom React hooks
│   ├── contexts/           # React context providers
│   ├── actions/            # API integration layer
│   ├── types/              # TypeScript type definitions
│   └── utils/              # Utility functions
├── public/                 # Static assets
├── .env                    # Environment configuration
├── package.json            # Dependencies
├── vite.config.ts          # Vite configuration
├── tailwind.config.js      # Tailwind configuration
└── tsconfig.json           # TypeScript configuration

Building for Production

Build the application:

npm run build

This creates an optimized production build in the dist/ directory:

Minified JavaScript and CSS
Code splitting for optimal loading
Optimized assets and images
Source maps for debugging

Preview the production build locally:

npm run preview

The preview server runs at http://localhost:4173.

Build Output

The dist/ directory contains:

index.html - Main HTML file
assets/ - JavaScript, CSS, and other assets * *.js - Bundled JavaScript with content hashes * *.css - Compiled Tailwind CSS * Images and fonts

Deployment

Static File Hosting

The built application is a static site that can be hosted on any web server or CDN:

Build the application:
```
npm run build
```
Deploy the dist/ directory to your hosting provider:
- Nginx: Serve from dist/ directory
- Apache: Serve from dist/ directory
- CDN: Upload dist/ contents (Cloudflare, AWS S3 + CloudFront, etc.)
Configure environment variables for production by updating .env before building:
```
VITE_API_URL=https://api.yourdomain.com
```

Single Page Application Routing

The application uses client-side routing. Configure your web server to redirect all requests to index.html:

Nginx:

location / {
    try_files $uri $uri/ /index.html;
}

Apache (.htaccess):

RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

API Configuration

The frontend requires a running DBCalm backend API. Ensure:

Backend API is accessible at the URL specified in VITE_API_URL
CORS is properly configured on the backend to accept requests from your frontend domain
SSL certificate is valid if using HTTPS (recommended)

Development Guidelines

Adding New Pages

Create a new component in src/pages/
Add routing in src/App.tsx
Add navigation links in src/components/Header.tsx

TypeScript Types

Define types in src/types/ for:

API request/response models
Component props
State management interfaces

API Integration

Use the actions pattern in src/actions/:

// src/actions/clients.ts
export async function fetchClients() {
    const response = await fetch(`${import.meta.env.VITE_API_URL}/clients`);
    return response.json();
}

Styling

Use Tailwind CSS utility classes:

<div className="bg-white p-4 rounded-lg shadow">
    <h1 className="text-2xl font-bold">Title</h1>
</div>

DaisyUI provides pre-styled components:

<button className="btn btn-primary">Click me</button>

Theme Support

The application supports light and dark themes via DaisyUI. Themes are configured in tailwind.config.js.

Troubleshooting

Build Errors

If TypeScript errors occur during build:

# Check TypeScript errors
npx tsc --noEmit

# Fix linting issues
npm run lint -- --fix

API Connection Issues

If the frontend can’t connect to the backend:

Verify VITE_API_URL in .env
Check backend API is running
Verify CORS configuration on backend
Check browser console for errors

SSL Certificate Errors

For local development with HTTPS backend:

Accept the self-signed certificate in your browser
Or configure backend with trusted certificates using mkcert

Port Conflicts

If port 5173 is in use:

# Vite will automatically try the next available port
npm run dev

# Or specify a port in vite.config.ts:
server: { port: 3000 }

Dependencies

Update dependencies:

npm update

# Check for outdated packages
npm outdated