OpsNexus ERP

OpsNexus ERP is a full-stack, role-based ERP platform for B2B teams that manage leads, clients, products, and post-sale claims.

What It Solves

OpsNexus ERP centralizes operational workflows that are often split across CRM, support, and internal admin tools:

• Lead intake, qualification, and operator assignment
• Lead-to-client conversion with product carryover
• Client account management and revenue visibility
• Claim submission, assignment, status tracking, and collaboration
• Role-specific dashboards for admin, supervisor, operator, and client users

Core Features

• Role-based access control (admin, supervisor, operator, client)
• User management with role changes, deactivation/reactivation, and supervisor linking
• Product catalog CRUD and product attachment to leads/clients
• Lead pipeline management and conversion to client records
• Client portal for viewing assigned products and filing claims
• Claim workflows with comments, file attachments, assignment, and notifications
• Analytics endpoints for summary metrics and charts
• Typed backend with Hono + Drizzle + Zod validation

Architecture

• frontend: Next.js App Router application (React + TypeScript + Tailwind CSS)
• backend: Hono API server (TypeScript)
• database: PostgreSQL (designed for Neon, compatible with standard Postgres)
• orm: Drizzle ORM with schema in drizzle/schema.ts
• auth: Better Auth with email/password and session cookies
• realtime: Supabase broadcast channels for claim notifications
• file upload: UploadThing integration for claim attachments

Detailed architecture docs: docs/ARCHITECTURE.md

Repository Structure

.
|-- backend/
|   |-- src/lib/                 # DB, auth, middleware, realtime helpers
|   |-- src/server/              # Hono app + route modules
|   `-- scripts/                 # Backend utility scripts
|-- frontend/
|   |-- src/app/                 # Next.js routes and layouts
|   |-- src/components/          # Shared UI and feature components
|   |-- src/lib/                 # API/auth/realtime clients
|   `-- src/hooks/               # Frontend hooks
|-- drizzle/
|   `-- schema.ts                # Drizzle schema source of truth
|-- scripts/                     # Root seed and maintenance scripts
|-- docs/                        # Project, architecture, and deployment docs
|-- API_DOCS.md                  # HTTP API reference
`-- .env.example                 # Required environment variables

Prerequisites

• Node.js 20+
• npm 10+
• PostgreSQL database

Quick Start

1. Install dependencies.

npm install
npm --prefix frontend install --legacy-peer-deps
npm --prefix backend install

2. Configure environment variables.

cp .env.example .env.local

Populate .env.local with your own values.

3. Apply database schema.

npx drizzle-kit push --config drizzle.config.ts

4. Seed demo data.

npm run seed

5. Start frontend and backend in separate terminals.

npm run dev:frontend
npm run dev:backend

• Frontend: http://localhost:3000
• Backend: http://localhost:3010

Environment Variables

See .env.example. Key variables:

• DATABASE_URL: PostgreSQL connection string
• AUTH_SECRET: Better Auth secret
• FRONTEND_URL: Allowed frontend origin for auth/CORS
• NEXT_PUBLIC_API_URL: Backend URL used by frontend
• UPLOADTHING_SECRET, UPLOADTHING_APP_ID: UploadThing config
• SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_ANON_KEY): Backend notifications
• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY: Frontend realtime notifications

Scripts

Root scripts:

• npm run dev:frontend - start Next.js dev server
• npm run dev:backend - start backend dev server
• npm run build - build backend then frontend
• npm run lint - run frontend linting
• npm run seed - seed database with demo data

Package-specific scripts:

• frontend: dev, build, start, lint
• backend: dev, build

Demo Credentials (Seed Data)

After running npm run seed:

• Admin: admin@cu4tro.com / 123456
• Supervisor: supervisor1@cu4tro.com / 123456
• Operator: operator1@cu4tro.com / 123456
• Client: client1@example.com / 123456

Use demo credentials for local testing only.

API Documentation

See API_DOCS.md for endpoint details and role access matrix.

Repository Standards

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md
• Deployment checklist: docs/DEPLOYMENT.md

Known Gaps

• Automated tests are not yet implemented.
• The root package currently includes legacy dependencies that can be pruned in a dedicated dependency cleanup pass.

License

MIT - see LICENSE.