A full-stack engineering operations platform that models real-world support workflows across L1, L2, and L3 teams with workflow enforcement, SLA management, audit logging, assignment ownership, RBAC, operational dashboards, and analytics.
Key Highlights:
- Enforced escalation workflows and state-machine transitions.
- Priority-driven SLA tracking and real-time breach detection.
- Immutable, tamper-evident audit trails for all critical actions.
- Role-based operational dashboards and analytics for engineering managers.
| Area | Features |
|---|---|
| Authentication | JWT Authentication, Registration, Protected Routes |
| Authorization | RBAC, Tier-Based Escalation Permissions |
| Ticketing | Creation, Assignment, Claiming, Ownership |
| Workflow | State Machine, Escalation Engine |
| SLA | Deadline Tracking, Breach Detection |
| Auditability | Immutable Audit Logs, Activity Center |
| Operations | Workspace, Team Operations Dashboard |
| Analytics | SLA Compliance, Resolution Metrics, Workload Distribution |
| Demo Data | Enterprise-grade deterministic dataset with 50+ realistic tickets, audit history, and SLA-aware workloads |
| Component | Status | Platform |
|---|---|---|
| Frontend | ✅ Live | Vercel |
| Backend API | ✅ Live | Render |
| Database | ✅ Live | Neon PostgreSQL |
- Frontend: https://esp-snowy-two.vercel.app/
- Backend API: https://esp-0uqk.onrender.com
- Swagger UI: https://esp-0uqk.onrender.com/docs
Internet
│
┌─────────────┴─────────────┐
│ │
▼ ▼
Frontend (Vercel) Backend API (Render)
│
▼
PostgreSQL (Neon)
ESP utilizes a robust, decoupled architecture separating the frontend presentation layer from a scalable backend REST API.
┌─────────────┐ ┌─────────────────────────┐
│ │ │ FastAPI API │
│ React │ REST API │ ┌────────┐ ┌────────┐ │
│ Frontend ├────────────►│ │ Auth │ │ RBAC │ │
│ │ │ └────────┘ └────────┘ │
└─────────────┘ │ ┌────────┐ ┌────────┐ │
│ │ SLA │ │ Audit │ │
│ └────────┘ └────────┘ │
└───────────┬─────────────┘
│
▼
┌────────────┐
│ PostgreSQL │
│ Database │
└────────────┘
Tickets flow deterministically through defined support tiers. Engineers can only escalate tickets if they have the necessary permissions.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ L1 Support │ │ L2 Support │ │ L3 Support │
│ (Triage) ├─────►│ (Adv. Triage)├─────►│(Engineering) │
└──────────────┘ └──────────────┘ └──────────────┘
A strict state machine governs ticket lifecycles, ensuring tickets cannot transition into invalid states.
┌──────┐ Assign/Claim ┌───────────┐ Resolve Issue ┌────────┐ Verify/Close ┌────────┐
│ OPEN ├─────────────────►│IN_PROGRESS├──────────────────►│RESOLVED├─────────────────►│ CLOSED │
└──┬───┘ └─────┬─────┘ └────────┘ └────────┘
▲ │
└────────────────────────────┘
Unassign / Reopen
- JWT Authentication: Secure, stateless session management.
- Protected Routes: UI components and API endpoints restricted based on authentication status.
- Role-Based Access Control (RBAC): Fine-grained permissions separating
ADMIN,ENGINEERING_MANAGER, and tieredSUPPORT_L1/L2/L3roles. - Unverified Account Lifecycle: Accounts that remain unverified are automatically deleted after the configured expiry period.
(Note: Seeded demo users are pre-verified, marked as system accounts, and are immune to cleanup. Additionally, SMTP cannot reliably determine mailbox existence synchronously during delivery, hence the background cleanup strategy.)
Register → Verification Email Sent → Account Pending Verification Verified within expiry: ↓ Account Activated Not Verified within expiry: ↓ Account and OTP automatically removed by cleanup.
- Ticket Creation & Assignment: Strict creation workflows and assignment rules.
- Ticket Ownership: Claiming mechanisms to lock ticket resolution to specific engineers.
- Ticket Explorer: Advanced filtering (by status, priority, SLA, assignee), sorting, and pagination.
- State Machine: Enforces valid status transitions.
- Escalation Engine: Deterministic promotion of tickets across support tiers (L1 → L2 → L3).
- Priority-Driven SLAs: Deadlines computed dynamically based on Ticket Priority (Low, Medium, High, Critical).
- SLA Breach Detection: Automated flagging of At-Risk and Breached tickets.
- Immutable Audit Logs: Tracking every mutation (status change, reassignment, escalation) with metadata.
- Activity Center: A global timeline view of all platform operations.
- Ticket Timelines: Granular history views on individual tickets.
- Personal Workspace: Curated views for individual engineers focusing on assigned workloads.
- Team Operations: Managerial views into tier-specific active tickets, unassigned queues, and breaches.
- Global Operations: High-level platform health summaries.
- Analytics: Real-time reporting on SLA compliance, resolution times, workload distributions, and escalation frequencies.
Backend:
- Framework: FastAPI
- Database ORM: SQLAlchemy
- Migrations: Alembic
- Database: PostgreSQL
- Data Validation: Pydantic
Frontend:
- Framework: React (Vite)
- Language: TypeScript
- HTTP Client: Axios
- Styling: TailwindCSS
- Data Visualization: Recharts
Infrastructure:
- Containerization: Docker & Docker Compose
engineering-support-platform
├── backend
│ ├── app
│ │ ├── api # FastAPI route handlers
│ │ ├── core # Config and security
│ │ ├── db # Database connection and sessions
│ │ ├── models # SQLAlchemy ORM models
│ │ ├── repositories # Data access layer
│ │ ├── schemas # Pydantic validation models
│ │ ├── seed # Deterministic demo dataset catalogs
│ │ └── services # Business logic
│ ├── migrations # Alembic migrations
│ └── scripts # Database seeding scripts
├── frontend
│ ├── public # Static assets
│ └── src
│ ├── components # Reusable UI components
│ ├── context # React context providers
│ ├── hooks # Custom React hooks
│ ├── pages # Top-level page components
│ ├── services # API client functions
│ └── types # TypeScript interfaces
└── docker-compose.yml # Docker configuration
Database Schema
├── USERS
│ ├── id (PK)
│ ├── email
│ ├── full_name
│ └── hashed_password
├── ROLES
│ ├── id (PK)
│ └── name
├── USER_ROLES (Join Table)
│ ├── user_id (FK -> USERS)
│ └── role_id (FK -> ROLES)
├── TICKETS
│ ├── id (PK)
│ ├── title
│ ├── description
│ ├── status
│ ├── priority
│ ├── support_level
│ ├── sla_due_at
│ ├── closed_at
│ ├── created_by_id (FK -> USERS)
│ └── assigned_to_id (FK -> USERS)
└── AUDIT_LOGS
├── id (PK)
├── action
├── entity_type
├── entity_id
├── event_metadata (JSON)
├── actor_id (FK -> USERS)
└── ticket_id (FK -> TICKETS)
The production deployment is pre-seeded with demo users, realistic tickets, audit history, and operational dashboards for evaluation.
The platform comes with a comprehensive seed script that provisions a realistic engineering organization.
Default Password for all accounts: Password123!
admin@esp.com(Admin User)manager@esp.com(Engineering Manager)
alice.l1@esp.com(Alice Johnson)john.l1@esp.com(John Doe)sarah.l1@esp.com(Sarah Connor)
bob.l2@esp.com(Bob Smith)mike.l2@esp.com(Mike Wazowski)
charlie.l3@esp.com(Charlie Brown)david.l3@esp.com(David Wallace)
To experience the platform's escalation enforcement:
- Create an Issue: Log in as
alice.l1@esp.comand create a high-priority ticket. - Claim & Escalate: Claim the ticket as Alice, realize it requires deeper investigation, and use the "Escalate" action to send it to the L2 queue.
- L2 Triage: Log out and log back in as
bob.l2@esp.com. Navigate to Team Operations to see the newly escalated ticket in the L2 unassigned queue. - Resolution: Bob claims the ticket, investigates, and changes the status to
Resolved. - Audit Trail: Log in as
manager@esp.comand view the Ticket Timeline or global Activity Center to see the complete immutable history of Alice's creation/escalation and Bob's resolution.
- Docker and Docker Compose
- Node.js (v18+)
- Python 3.10+
- Poetry
git clone https://github.com/your-username/engineering-support-platform.git
cd engineering-support-platformESP uses dedicated environments to prevent accidental data loss:
- Development
- Container:
esp-postgres-dev - Database:
esp_db
- Container:
- Testing
- Container:
esp-postgres-test - Database:
esp_test_db
- Container:
- Production
- Neon PostgreSQL
Warning
Never point backend/.env.test at the development database (esp_db). The test suite aggressively truncates the database, which will result in data loss if configured incorrectly.
Start the PostgreSQL containers:
docker-compose up -dcd backend
poetry install
cp .env.example .envEnsure your .env is populated with the correct database and SMTP configurations:
DATABASE_URL=postgresql://user:password@localhost:5432/esp
SECRET_KEY=your-secure-secret-key
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp-relay.brevo.com | smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
EMAIL_FROM_ADDRESS=noreply@esp.com
EMAIL_FROM_NAME="Engineering Support Platform (ESP)"
SMTP_USE_TLS=trueApply database migrations:
poetry run alembic upgrade headSeed the database with the enterprise demo dataset (generates a production-quality environment with 55 realistic tickets, audit logs, and engineer workloads):
poetry run python scripts/seed_demo_data.pyStart the backend server:
poetry run uvicorn app.main:app --reloadIn a new terminal:
cd frontend
npm install
npm run devThe application will be available at http://localhost:5173.
Detailed documentation and interactive consoles are available for the backend API:
- API Reference: docs/api.md
- Swagger UI: https://esp-0uqk.onrender.com/docs
While ESP is fully functional, future iterations may include:
- Notifications: Real-time WebSocket notifications and Slack/Email integrations.
- Saved Views: User-configurable ticket filter presets.
- Advanced Analytics: Trend lines, forecasting, and historical capacity planning.
- Scheduled Reports: Automated PDF/CSV exports of SLA metrics sent to engineering managers.
This project is licensed under the Apache License 2.0. See the LICENSE file for more details.