OpsPilot

Internal operations platform for managing customers, support tickets, notes, and team workflows.

Tech Stack

• Backend: Kotlin, Spring Boot, Spring Security, Spring Data JPA, Flyway
• Frontend: React, TypeScript, Vite, React Router, TanStack Query, Zustand, React Hook Form, Zod
• Database: PostgreSQL
• Infra: Docker Compose

Architecture Overview

• Backend: Kotlin + Spring Boot REST API with Spring Data JPA for persistence and Flyway for schema migrations.
• Frontend: React + TypeScript single-page app using typed API integration for auth and operations workflows.
• Database: PostgreSQL running locally via Docker Compose.

Features

• JWT authentication (ADMIN, AGENT)
• Customer management (list/create/detail/update)
• Ticket management with notes
• Dashboard summary (ticket totals, status breakdown, recent tickets)
• Knowledge article management
• Admin user management (role updates, active toggle)

Project Structure

opspilot/
  backend/
  frontend/
  docker-compose.yaml
  README.md

Environment Variables

Backend example: backend/.env.example

• DATABASE_URL (default: jdbc:postgresql://127.0.0.1:5432/opspilot)
• DATABASE_USERNAME (default: postgres)
• DATABASE_PASSWORD (default: postgres)
• SERVER_PORT (default: 8080)
• JWT_SECRET (required for non-local environments)
• JWT_EXPIRATION_MS (default: 86400000)
• CORS_ALLOWED_ORIGINS (default: http://localhost:5173)

Frontend example: frontend/.env.example

• VITE_API_URL (default expected: http://localhost:8080)

Run Locally

1) Start PostgreSQL

From repo root:

docker compose up -d postgres

2) Start Backend

From backend/:

Windows:

gradlew.bat bootRun

Unix/macOS:

./gradlew bootRun

If port 8080 is already in use, run the backend on an alternate port:

./gradlew bootRun --args="--server.port=18080"

3) Start Frontend

From frontend/:

npm install
npm run dev

Frontend runs at http://localhost:5173.

Notes

• Frontend API client normalizes VITE_API_URL so both http://localhost:8080 and http://localhost:8080/api work safely.
• First registered user is automatically ADMIN (dev bootstrap path).

Key Engineering Decisions

• JWT authentication keeps API calls stateless and aligns with role-based authorization needs (ADMIN, AGENT).
• Flyway is used to keep schema changes explicit, versioned, and reproducible across environments.
• Backend follows controller/service/repository separation so HTTP concerns, business logic, and persistence remain cleanly decoupled.

API Overview

• Auth: /api/auth/*
• Customers: /api/customers/*
• Tickets + Notes: /api/tickets/*
• Dashboard: /api/dashboard/summary
• Articles: /api/articles/*
• Admin Users: /api/admin/users/* (ADMIN only)

Screenshot

Future Improvements

• Add focused integration tests for auth, customers, and ticket lifecycle endpoints.
• Add pagination and filtering for larger customer/ticket datasets.
• Add structured request logging and metrics for improved operational visibility.