Development Guide

Welcome to the Maraikka Development Guide! This comprehensive guide will help you set up your development environment, understand the codebase architecture, and contribute effectively to the project.

Repository Overview

Maraikka consists of multiple repositories that work together to provide the complete documentation platform experience:

Core Repositories

1. Maraikka Documentation Platform

Repository: maraikka/maraikka-core
Description: Main application with documentation editor, collaboration features, and publishing engine
Technology Stack: Next.js, React, TypeScript, Prisma, PostgreSQL
License: MIT

2. Maraikka Desktop Application

Repository: maraikka/maraikka-desktop
Description: Cross-platform desktop application built with Electron
Technology Stack: Electron, React, TypeScript
License: MIT

3. Maraikka Documentation (This Site)

Repository: maraikka/maraikka-docs
Description: Official documentation and website
Technology Stack: Next.js, Nextra, MDX
License: MIT

Development Environment Setup

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js: Version 18.0 or higher
npm: Version 8.0 or higher (or pnpm 7.0+)
Git: Latest stable version
Docker: For containerized development (optional but recommended)

Recommended Tools

VS Code: With recommended extensions
PostgreSQL: For local database development
Redis: For caching and session management
nvm/nvs: Node version management

Quick Start

1. Clone the Repository


# Clone the main application
git clone https://github.com/puzzlers-labs/maraikka-core.git
cd maraikka-core
 
# Or clone the documentation site
git clone https://github.com/puzzlers-labs/maraikka-docs.git
cd maraikka-docs

2. Install Dependencies


# Using npm
npm install
 
# Using pnpm (recommended)
pnpm install
 
# Using yarn
yarn install

3. Environment Configuration


# Copy environment template
cp .env.example .env.local
 
# Edit environment variables
# Update database URLs, API keys, and other configuration

4. Database Setup (Core Application)


# Start PostgreSQL with Docker
docker-compose up -d postgres
 
# Run database migrations
npx prisma migrate dev
 
# Seed the database (optional)
npx prisma db seed

5. Start Development Server


# Start the development server
npm run dev
 
# The application will be available at http://localhost:3000

Project Structure

Core Application Architecture


maraikka-core/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── (dashboard)/       # Dashboard pages
│   ├── (editor)/          # Editor interface
│   └── globals.css        # Global styles
├── components/            # Reusable React components
│   ├── ui/               # Base UI components
│   ├── editor/           # Editor-specific components
│   └── shared/           # Shared components
├── lib/                  # Utility libraries
│   ├── auth/            # Authentication utilities
│   ├── db/              # Database utilities
│   └── utils/           # General utilities
├── prisma/              # Database schema and migrations
├── public/              # Static assets
├── styles/              # Additional stylesheets
└── types/               # TypeScript type definitions

Documentation Site Structure


maraikka-docs/
├── content/             # Documentation content
│   ├── features/       # Feature documentation
│   ├── user-guide/     # User guides
│   ├── getting-started/ # Getting started guides
│   └── development-guide/ # Development documentation
├── components/         # Custom components
├── public/            # Static assets and images
├── styles/            # Custom styles
└── theme.config.tsx   # Nextra theme configuration

Technology Stack

Frontend Technologies

Next.js 14: React framework with App Router
React 18: UI library with modern features
TypeScript: Type safety and developer experience
Tailwind CSS: Utility-first CSS framework
Radix UI: Accessible component primitives
Framer Motion: Animation library

Backend Technologies

Next.js API Routes: Server-side API endpoints
Prisma: Database ORM and query builder
PostgreSQL: Primary database
Redis: Caching and session storage
NextAuth.js: Authentication framework
Zod: Runtime type validation

Development Tools

ESLint: Code linting and formatting
Prettier: Code formatting
Husky: Git hooks
Lint-staged: Staged file linting
Jest: Unit testing framework
Playwright: End-to-end testing

Building from Source

Production Build

Core Application


# Install dependencies
pnpm install
 
# Build the application
pnpm build
 
# Start production server
pnpm start

Documentation Site


# Install dependencies
pnpm install
 
# Build static site
pnpm build
 
# Serve locally (optional)
pnpm preview

Docker Build

Using Docker Compose


# Build and start all services
docker-compose up --build
 
# Build specific service
docker-compose build maraikka-core

Custom Docker Build


# Build Docker image
docker build -t maraikka-core .
 
# Run container
docker run -p 3000:3000 maraikka-core

Development Workflow

Code Standards

TypeScript Configuration

Strict mode enabled
Path aliases configured
Consistent import/export patterns

Code Style

ESLint with custom rules
Prettier for consistent formatting
Conventional commit messages
Component naming conventions

Testing Strategy

Unit Tests


# Run unit tests
npm run test
 
# Run tests in watch mode
npm run test:watch
 
# Generate coverage report
npm run test:coverage

Integration Tests


# Run integration tests
npm run test:integration

End-to-End Tests


# Run E2E tests
npm run test:e2e
 
# Run E2E tests in UI mode
npm run test:e2e:ui

Database Management

Migrations


# Create new migration
npx prisma migrate dev --name migration_name
 
# Reset database
npx prisma migrate reset
 
# Deploy migrations to production
npx prisma migrate deploy

Schema Management


# Generate Prisma client
npx prisma generate
 
# Open Prisma Studio
npx prisma studio
 
# Seed database
npx prisma db seed

Contributing Guidelines

Getting Started

Fork the repository
Create a feature branch
Make your changes
Write tests for new functionality
Ensure all tests pass
Submit a pull request

Pull Request Process

Description: Provide clear description of changes
Testing: Include test coverage for new features
Documentation: Update relevant documentation
Review: Address feedback from maintainers
Merge: Squash and merge after approval

Issue Reporting

Use issue templates
Provide reproduction steps
Include environment details
Add relevant labels

API Development

REST API Endpoints


// Example API route structure
// app/api/documents/route.ts
 
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
 
export async function GET(request: NextRequest) {
  const session = await auth();
 
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
 
  const documents = await db.document.findMany({
    where: { userId: session.user.id },
  });
 
  return NextResponse.json(documents);
}

Database Schema


// Example Prisma schema
model Document {
  id          String   @id @default(cuid())
  title       String
  content     String?
  published   Boolean  @default(false)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  userId      String
  user        User     @relation(fields: [userId], references: [id])
}

Performance Optimization

Development Performance

Hot Module Replacement: Fast development feedback
Incremental Static Regeneration: Efficient builds
Code Splitting: Optimized bundle sizes
Image Optimization: Next.js image optimization

Production Optimizations

Bundle Analysis: Analyze and optimize bundle size
Database Indexing: Optimize database queries
Caching Strategies: Implement effective caching
CDN Integration: Global content delivery

Deployment

Platform Options

Vercel: Recommended for Next.js applications
Netlify: Alternative static site hosting
AWS: Custom cloud deployment
Docker: Containerized deployment

Environment Variables


# Required environment variables
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="your-secret-key"
NEXTAUTH_URL="http://localhost:3000"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"