Nekometrics Development Guide

Development instructions for Nekometrics, a Next.js application that centralizes metrics and KPIs from multiple external services (Google Analytics, Facebook/Instagram, Twitter, Mailchimp, WooCommerce, EDD) into customizable dashboards.

Project Commands

When working with this codebase, use these commands:

```bash

Development server (runs on port 4002)

pnpm dev

Build for production

pnpm build

Start production server (port 4001)

pnpm start

Stage server (port 4003)

pnpm start-stg

Analyze bundle size

pnpm analyze

```

Architecture Understanding

Before making changes, understand these core architectural components:

1. Service Integration Layer (`libs/services/`)

Each external service (Google Analytics, Facebook, Twitter, etc.) has its own module handling:

OAuth authentication flow

API data fetching

Token refresh logic

The `Services` class (`libs/services.js`) acts as the central registry, mapping widget types to their data fetching functions.

2. Widget System

**WidgetsFactory** (`components/widgets/WidgetsFactory.js`):

Central component that renders all widget types

Handles refresh intervals, error states, loading states

Manages settings modals for each widget

**WidgetsRepository** (`components/widgets/WidgetsRepository.js`):

Maps widget types to their component implementations

Each widget has two components:

- Display component (e.g., `google/AnalyticsVisits.js`)

- Settings component (e.g., `google/AnalyticsVisitsSettings.js`)

3. API Structure (`pages/api/`)

Key endpoints:

`dashboard/[dashId].js` - Dashboard CRUD operations

`widget/[widgetId].js` - Widget management

`oauth/[service].js` - OAuth callback handlers

`metrics/[widgetId].js` - Metrics data fetching

`job/refresh.js` - Background refresh job

`job/cleanup.js` - Cleanup job

4. Data Flow

1. Widgets fetch data via `/api/metrics/[widgetId]`

2. API routes use the Services layer to call external APIs

3. Data is cached in MongoDB with configurable refresh intervals

4. Widgets auto-refresh at randomized intervals to prevent simultaneous requests

5. Authentication

Custom authentication system:

MongoDB for user storage

bcrypt for password hashing

Session management via cookies

No third-party auth library

Environment Configuration

Create `.env.local` from `.env` template with:

```bash

MongoDB connection

DATABASE_URL=mongodb://...

SMTP for email

SMTP_HOST=...

SMTP_PORT=...

SMTP_USER=...

SMTP_PASS=...

OAuth credentials for each service

GOOGLE_CLIENT_ID=...

GOOGLE_CLIENT_SECRET=...

FACEBOOK_APP_ID=...

FACEBOOK_APP_SECRET=...

TWITTER_API_KEY=...

TWITTER_API_SECRET=...

MAILCHIMP_CLIENT_ID=...

MAILCHIMP_CLIENT_SECRET=...

Session secret

SECRET=...

```

Database Schema

MongoDB collections:

**User** - User accounts and authentication

**Dashboard** - Dashboard configurations and layouts

**Widget** - Widget instances with settings and cached metrics

**Service** - Connected external services per user (OAuth tokens)

Technology Stack

**Framework**: Next.js with standalone output mode

**Runtime**: Node.js 20+

**Package Manager**: pnpm (migrated from yarn)

**UI**: Material-UI v4, styled-components

**Layout**: React Grid Layout for drag-and-drop

**Database**: MongoDB

**Process Manager**: PM2 (production)

**Analytics**: Plausible Analytics integration

Development Guidelines

Adding a New Service Integration

1. Create service module in `libs/services/[serviceName]/`

2. Implement OAuth flow in `pages/api/oauth/[serviceName].js`

3. Add data fetching functions

4. Register service in `Services` class (`libs/services.js`)

5. Create widget components in `components/widgets/[serviceName]/`

6. Register widgets in `WidgetsRepository.js`

Adding a New Widget

1. Create widget component in appropriate service directory

2. Create corresponding settings component

3. Register in `WidgetsRepository.js` with:

- Widget component

- Settings component

- Default configuration

4. Add metrics endpoint handler if needed

Debugging Data Flow

1. Check widget component for API endpoint used

2. Trace API route in `pages/api/metrics/[widgetId].js`

3. Follow to Services layer method

4. Check external service module for actual API call

5. Verify MongoDB caching logic

Common Tasks

**Refresh intervals**: Configured per-widget in settings, stored in Widget document

**OAuth tokens**: Stored in Service collection, automatically refreshed by service modules

**Cache invalidation**: Handled by refresh job (`pages/api/job/refresh.js`)

**Error handling**: Widget components display error states; API routes return standardized error responses

Deployment

Configured for Coolify deployment:

Multi-stage Dockerfile

Health check at `/api/health`

Standalone Next.js build

See `DEPLOY_COOLIFY.md` for full instructions

Port Configuration

Development: 4002

Production: 4001

Staging: 4003

All configurable via environment variables.

nekometrics-development