Skip to main content
Prerequisite: Complete the Quick Start Guide before proceeding with development.

​
Development Environment

Meridian uses a monorepo structure with separate frontend and backend applications that communicate via REST APIs and WebSockets.

​
Project Structure

Meridian-Mono/
├── Meridian/
│   ├── frontend/          # React application
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── context/
│   │   │   ├── pages/
│   │   │   └── hooks/
│   │   └── package.json
│   ├── backend/           # Node.js/Express API
│   │   ├── routes/
│   │   ├── schemas/
│   │   ├── services/
│   │   └── package.json
│   └── README.md
├── Meridian-Mobile/       # React Native mobile app
└── Meridian-Mintlify/     # Documentation site

​
Running Development Servers

​
Option 1: Run Both Together

From the root directory: 
npm run dev
This concurrently runs:
  • Frontend on http://localhost:3000
  • Backend on http://localhost:5001

​
Option 2: Run Separately

Frontend: 
cd Meridian/frontend
npm start
Backend: 
cd Meridian/backend
npm start

​
Custom Ports

Frontend: 
PORT=3001 npm start
Backend: 
PORT=5002 npm start

​
Development Workflow

​
1. Create a Feature Branch

git checkout -b feature/your-feature-name

​
2. Make Your Changes

  • Frontend: Edit files in Meridian/frontend/src/
  • Backend: Edit files in Meridian/backend/

​
3. Test Your Changes

# Frontend tests
cd Meridian/frontend
npm test

# Backend tests
cd Meridian/backend
npm test

​
4. Format Code

# Format all code
npm run format

# Or use Prettier directly
npx prettier --write "**/*.{js,jsx,scss,json}"

​
5. Commit and Push

git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

​
Frontend Development

​
Key Technologies

  • React - UI framework
  • SCSS - Styling
  • Context API - State management
  • React Router - Navigation
  • WebSocket - Real-time updates

​
Component Structure

// Example component structure
import React from 'react';
import { useAuth } from '../context/AuthContext';
import './Component.scss';

const Component = () => {
  const { user } = useAuth();
  
  return (
    <div className="Component">
      <h1>Hello, {user?.name}</h1>
    </div>
  );
};

export default Component;

​
State Management

Meridian uses React Context API for global state:
  • AuthContext - User authentication
  • CacheContext - API response caching
  • ErrorContext - Error handling
  • NotificationContext - Notifications
  • WebSocketContext - Real-time connections

​
Styling Guidelines

  • Use SCSS modules for component styles
  • Follow BEM naming convention
  • Keep styles co-located with components
.Component {
  &__header {
    font-size: 1.5rem;
  }
  
  &__content {
    margin: 1rem 0;
  }
}

​
Backend Development

​
API Structure

backend/
├── routes/          # API route handlers
├── schemas/         # Data validation schemas
├── services/        # Business logic
├── middlewares/     # Express middlewares
└── utilities/       # Helper functions

​
Creating a New Route

// routes/example.js
const express = require('express');
const router = express.Router();
const { validateRequest } = require('../middlewares/validation');

router.get('/example', validateRequest, async (req, res) => {
  try {
    // Your logic here
    res.json({ success: true });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

module.exports = router;

​
Database Migrations

cd Meridian/backend
npm run migrate        # Run migrations
npm run migrate:rollback  # Rollback last migration

​
Code Quality

​
Linting

# Frontend
cd Meridian/frontend
npm run lint

# Backend
cd Meridian/backend
npm run lint

​
Type Checking

For TypeScript files: 
npm run type-check

​
Debugging

​
Frontend Debugging

  1. Use React Developer Tools browser extension
  2. Check browser console for errors
  3. Use console.log() strategically (remove before committing)

​
Backend Debugging

  1. Use console.log() or debugger statements
  2. Check server logs in terminal
  3. Use Postman/Insomnia for API testing

​
Database Debugging

# Connect to PostgreSQL
psql meridian

# View tables
\dt

# Query data
SELECT * FROM users LIMIT 10;

​
Testing

​
Frontend Tests

cd Meridian/frontend
npm test              # Run tests
npm test -- --watch   # Watch mode
npm test -- --coverage # Coverage report

​
Backend Tests

cd Meridian/backend
npm test              # Run tests
npm test -- --watch   # Watch mode

​
Environment Variables

Never commit .env files. Use .env.example as a template: 
# Copy example file
cp .env.example .env

# Edit with your values
nano .env

​
Common Issues

Solution: Delete node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install
Solution: Kill the process using the port:
lsof -ti:3000 | xargs kill
Solution: Ensure PostgreSQL is running and credentials are correct:
# Check PostgreSQL status
brew services list  # macOS
sudo systemctl status postgresql  # Linux
Solution: Check backend WebSocket server is running and CORS is configured correctly.

​
Best Practices

  1. Write Descriptive Commits: Use conventional commit format 
    feat: add user authentication
fix: resolve login redirect issue
docs: update API documentation
  2. Keep Components Small: Single responsibility principle
  3. Use TypeScript: For better type safety (where applicable)
  4. Test Your Code: Write unit and integration tests
  5. Document Complex Logic: Add comments for non-obvious code
  6. Follow Code Style: Use Prettier and ESLint

​
Resources

Frontend Guide

Detailed frontend architecture guide

API Reference

Complete API documentation

SAML Auth

Authentication setup guide

Quick Start

Setup instructions
Need help? Check the Quick Start Guide or reach out to the development team.