Developer Guide

Welcome to the Earthquake Catalogue Platform Developer Guide. This guide provides technical information for developers who want to contribute to the project, extend its functionality, or integrate it with other systems.

Overview

The Earthquake Catalogue Platform is built with modern web technologies:

  • Frontend: Next.js 13+ with App Router, React, TypeScript

  • Backend: Next.js API Routes (serverless)

  • Database: MongoDB with full QuakeML 1.2 schema

  • UI: Tailwind CSS, shadcn/ui components

  • Maps: Leaflet with React Leaflet

  • Testing: Jest, React Testing Library

What You’ll Learn

This developer guide covers:

  1. Architecture - System design, components, and data flow

  2. Setup - Development environment configuration

  3. Database Schema - MongoDB collections and indexes

  4. API Development - Creating and extending API endpoints

  5. Testing - Writing and running tests

  6. Contributing - Guidelines for contributing code

  7. Implementation Notes - Technical deep dives and summaries

Technology Stack

Frontend

Technology

Purpose

Next.js 13+

React framework with App Router

TypeScript

Type-safe development

Tailwind CSS

Utility-first CSS framework

shadcn/ui

High-quality React components (40+ Radix UI components)

Recharts

Data visualization library

Leaflet

Interactive map library

React Hook Form

Form validation and management

Zod

Schema validation

Backend

Technology

Purpose

Next.js API Routes

Serverless API endpoints

MongoDB

NoSQL database with QuakeML 1.2 schema

NextAuth.js

Authentication and session management

xml2js

XML parsing for QuakeML

uuid

Unique identifier generation

Testing

Technology

Purpose

Jest

JavaScript testing framework

Testing Library

React component testing

@types packages

TypeScript type definitions

Project Structure

catalogofcatalogs/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── catalogues/   # Catalogue CRUD
│   │   ├── import/       # GeoNet import
│   │   ├── merge/        # Catalogue merging
│   │   └── upload/       # File upload
│   ├── analytics/         # Analytics page
│   ├── catalogues/        # Catalogue pages
│   ├── dashboard/         # Dashboard
│   ├── import/            # Import page
│   ├── merge/             # Merge page
│   └── upload/            # Upload page
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── catalogues/       # Catalogue components
│   ├── import/           # Import components
│   ├── merge/            # Merge components
│   └── upload/           # Upload components
├── lib/                   # Core library code
│   ├── mongodb.ts        # MongoDB client
│   ├── db.ts             # Database queries
│   ├── parsers.ts        # File parsers
│   ├── earthquake-utils.ts
│   ├── quality-scoring.ts
│   └── types/            # TypeScript types
├── scripts/               # Utility scripts
├── __tests__/             # Jest tests
└── docs/                  # Documentation

Next Steps

Ready to start developing? Head over to Development Setup to configure your development environment.