OpsCore — Incident Management System

OpsCore is an MVP web application for operational incident management in industrial environments.

The platform helps teams replace informal incident tracking through WhatsApp messages, paper forms, or isolated spreadsheets with a centralized workflow for reporting incidents, assigning responsible technicians, recording applied solutions, and preserving operational traceability.

This project is part of a No Country simulation focused on building a real-world prototype for an operations consulting scenario.

---

Current MVP Status

The MVP core flow is currently functional and connected to the real backend API.

Validated flow:

Login
→ Operator creates an incident
→ Supervisor assigns a technician
→ Technician resolves the incident
→ Supervisor / Manager reviews traceability

Current status:

• Frontend integrated with the real Django REST Framework backend.
• Backend deployed on Render.
• Frontend deployed through Vercel.
• Authentication working through HttpOnly cookies.
• Private routes protected.
• Sidebar filtered by authenticated user role.
• Incident creation connected to the real API.
• Incident list and detail connected to the real API.
• Technician assignment working for supervisor and manager roles.
• Incident resolution connected to the real API.
• Main mock/local incident flow removed.
• QA and demo documentation available under the Docs/ folder.

The project is ready for production deployment as an MVP release candidate, pending final QA validation.

---

Problem

Industrial incidents are often reported using paper forms, WhatsApp messages, or informal communication channels.

This creates several operational issues:

• Lack of traceability.
• No centralized incident history.
• Difficulty measuring response and resolution times.
• Repeated root causes without structured analysis.
• Poor visibility for supervisors and plant managers.
• Delays in communication between operators, supervisors, and technicians.

OpsCore addresses these problems by providing a centralized, mobile-friendly, and role-based incident management platform.

---

Objective

Build a functional prototype that allows an industrial plant to:

• Report incidents from any device.
• Track incidents through different resolution stages.
• Assign responsible technicians.
• Register applied solutions.
• Measure operational response times.
• Classify root causes by type and area.
• Detect recurring issues to reduce critical incidents over time.

---

Main Users

Operator

Reports incidents directly from the production line using a mobile-optimized form.

Supervisor

Reviews incident reports, monitors open cases, assigns technicians, and tracks progress.

Technician

Resolves assigned incidents and records the applied solution.

Plant Manager

Reviews operational information, response metrics, and recurring root causes to support decision-making.

Admin

Has broader access to operational views and management actions according to backend permissions.

---

Core Workflow

1. An operator detects a machine failure, accident, or quality deviation.
2. The operator logs in and creates a new incident report.
3. The incident is stored in the backend and appears in the incident list and detail views.
4. A supervisor reviews the incident.
5. The supervisor assigns an active technician.
6. The assigned technician reviews the incident.
7. The technician resolves the incident and records the applied solution.
8. The system persists the final state and traceability data.
9. Supervisors and managers review the incident lifecycle through the application.

---

MVP Scope

The current MVP validates the main operational incident management flow:

• Real user authentication.
• Protected private routes.
• Role-based navigation.
• Incident creation by operators.
• Incident listing and detail views.
• Technician assignment by supervisors or managers.
• Incident resolution by assigned technicians.
• Basic traceability through incident history and status changes.
• Dashboard and reports views for operational review.

The validated core workflow is:

Operator creates an incident
Supervisor assigns a technician
Technician resolves the incident
Supervisor / Manager reviews traceability

---

Tech Stack

Frontend

• Next.js App Router.
• React.
• JavaScript.
• Tailwind CSS v4.
• Vercel deployment.
• Reusable components.
• Protected routes.
• Role-based UI guards.
• Loading, error, and empty states.

Backend

• Django REST Framework.
• Render deployment.
• HttpOnly cookie authentication.
• Role-based permissions.
• REST API.
• Real incident persistence.

Tools

• Git.
• GitHub.
• Vercel.
• Render.
• Postman.
• Jira / Trello.
• No Country platform.

---

Production Environment

Repository

https://github.com/No-Country-simulation/S04-26-Equipo-19-Web-App-Development

Backend API

https://s04-26-equipo-19-web-app-development.onrender.com/api

Frontend Deployment

Add current Vercel Production URL here.

Required Frontend Environment Variable

NEXT_PUBLIC_API_URL=https://s04-26-equipo-19-web-app-development.onrender.com/api

---

Language

The project documentation is written in English for evaluation, collaboration, and No Country documentation purposes.

The application UI is currently in Spanish because the MVP is designed for Spanish-speaking operational teams.

---

Authentication

Authentication is handled by the backend through HttpOnly cookies.

The frontend:

• Uses credentials: "include" in API requests.
• Does not store access or refresh tokens in localStorage.
• Does not send Authorization: Bearer headers.
• Validates the active session through GET /api/auth/me/.
• May cache only non-sensitive user data for UI rendering.

Auth endpoints:

POST /api/auth/login/
POST /api/auth/logout/
POST /api/auth/token/refresh/
GET  /api/auth/me/

---

User Roles

Role	Main Responsibility
Operator	Report incidents from the production line
Supervisor	Review, assign, and monitor incidents
Technician	Resolve assigned incidents
Manager	Review operational information, reports, and traceability
Admin	Full or extended access according to backend permissions

---

Role-Based Navigation

Sidebar navigation changes according to the authenticated user role.

Role	Visible sections
Operator	Dashboard, Incidents, Report incident
Supervisor	Dashboard, Incidents, Reports
Technician	Dashboard, Incidents
Manager	Dashboard, Incidents, Reports
Admin	Dashboard, Incidents, Report incident, Reports

This is UX-level protection. Backend authorization remains the source of truth.

---

Protected Routes

Private routes:

/dashboard
/incidents
/incidents/[id]
/incidents/new
/reports

Expected behavior:

• Without a valid session, the user is redirected to /.
• With a valid session, access is allowed according to role.
• Session validation is performed through /api/auth/me/.
• Some pages display an access-not-available state when the role is not allowed.

Role-based page access:

Route	Allowed roles
/incidents/new	Operator, Admin
/reports	Supervisor, Manager, Admin

---

Main API Endpoints

Authentication

POST /api/auth/login/
POST /api/auth/logout/
POST /api/auth/token/refresh/
GET  /api/auth/me/

Incidents / Reports

GET    /api/reportes/
POST   /api/reportes/
GET    /api/reportes/<id>/
PATCH  /api/reportes/<id>/asignar/
PATCH  /api/reportes/<id>/resolver/
GET    /api/reportes/<id>/adjuntos/
GET    /api/reportes/dashboard/

Catalogs

GET /api/areas/
GET /api/tipos-incidente/
GET /api/causas-raiz/
GET /api/usuarios/tecnicos/

Important note:

GET /api/usuarios/

should not be used for the technician assignment selector because the generic users endpoint is restricted. The frontend assignment flow must use:

GET /api/usuarios/tecnicos/

---

Implemented Flow

1. Login

The backend validates credentials, sets HttpOnly cookies, and the frontend validates the active session through:

GET /api/auth/me/

2. Incident Creation

Expected roles:

operator
admin

Endpoint:

POST /api/reportes/

The form loads real incident types from:

GET /api/tipos-incidente/

Incident creation no longer uses mock data or local persistence.

3. Incident List

Endpoint:

GET /api/reportes/

The list displays real backend incidents adapted for the frontend UI.

4. Incident Detail

Endpoint:

GET /api/reportes/<id>/

The detail view displays:

• Description.
• Area.
• Type.
• Priority.
• Status.
• Shift.
• Location.
• Dates.
• Reporter.
• Assigned technician.
• History.
• Files.
• Applied solution when available.

5. Technician Assignment

Endpoint:

PATCH /api/reportes/<id>/asignar/

Technician selector endpoint:

GET /api/usuarios/tecnicos/

Expected body:

{
  "asignado_a": 5
}

Expected roles:

supervisor
manager
admin

Current status:

Supervisor and manager can assign technicians.

6. Incident Resolution

Endpoint:

PATCH /api/reportes/<id>/resolver/

Expected body:

{
  "solucion": "Description of the applied solution."
}

Expected role:

assigned technician

Expected result:

• Status changes to closed/resolved.
• Solution is saved.
• Resolution date is registered.
• The change persists in list and detail views.

---

Project Structure

S04-26-Equipo-19-Web-App-Development/
│
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   │   ├── auth/
│   │   │   ├── dashboard/
│   │   │   ├── incidents/
│   │   │   ├── layout/
│   │   │   ├── reports/
│   │   │   └── ui/
│   │   ├── constants/
│   │   ├── hooks/
│   │   ├── lib/
│   │   └── utils/
│   └── package.json
│
├── Backend/
│   └── Django REST Framework API
│
├── Docs/
│   ├── frontend-qa-checklist.md
│   ├── frontend-status.md
│   ├── demo-script.md
│   ├── resources.md
│   └── MVP-STATUS.md
│
├── README.md
└── .gitignore

---

Internal Documentation

The following documents are available in the repository under the Docs/ folder:

Docs/frontend-qa-checklist.md
Docs/frontend-status.md
Docs/demo-script.md
Docs/resources.md
Docs/MVP-STATUS.md

Recommended usage:

• frontend-qa-checklist.md: use before demo or after each important merge.
• frontend-status.md: use to understand the current technical status of the frontend.
• demo-script.md: use to present the MVP flow clearly and consistently.
• resources.md: use as a quick reference for links, commands, endpoints, and QA checks.
• MVP-STATUS.md: use to review the current MVP scope and validation state.

---

Useful Frontend Commands

Run from the frontend/ folder.

Install dependencies

npm install

Development server

npm run dev

Build

npm run build

Lint

npm run lint

---

Useful Git Flow

Start a new branch

git checkout develop
git pull origin develop
git checkout -b feature/example-branch

Push branch

git push origin feature/example-branch

After merge

git checkout develop
git pull origin develop
git branch -d feature/example-branch
git push origin --delete feature/example-branch

Production release candidate

git checkout develop
git pull origin develop
git checkout main
git pull origin main
git merge develop
git push origin main

---

QA Quick Flow

Use this flow for a fast validation before demo:

Login as operator
→ Create incident
→ Confirm incident appears in list
→ Open incident detail
→ Logout

Login as supervisor
→ Assign technician
→ Confirm status changes to in progress
→ Reload and confirm assignment persists
→ Logout

Login as technician
→ Resolve incident
→ Confirm incident is closed/resolved
→ Reload and confirm resolution persists
→ Logout

Login as manager or supervisor
→ Open dashboard
→ Open reports
→ Review traceability
→ Logout

---

Browser Checks

Use Chrome DevTools.

Network

Confirm:

POST  /api/auth/login/                  → 200
GET   /api/auth/me/                     → 200 after login
GET   /api/reportes/                    → 200
POST  /api/reportes/                    → 200 or 201
GET   /api/usuarios/tecnicos/           → 200
PATCH /api/reportes/<id>/asignar/       → 200 if role is allowed
PATCH /api/reportes/<id>/resolver/      → 200 if role is allowed

Application → Storage

Confirm:

• No access token in localStorage.
• No refresh token in localStorage.
• Session cookies exist under the backend domain after login.
• Cookies are HttpOnly.
• Cookies are Secure in production.
• Cookies use SameSite=None in production.

---

Demo Preparation Checklist

• Confirm Vercel Production URL.
• Confirm Render backend is awake.
• Confirm production environment variable NEXT_PUBLIC_API_URL.
• Confirm backend CORS allows the production frontend domain.
• Confirm test credentials for all roles.
• Confirm at least one active technician exists.
• Confirm operator can create an incident.
• Confirm supervisor can assign a technician.
• Confirm assigned technician can resolve the incident.
• Confirm dashboard loads.
• Confirm reports load.
• Confirm there are no visible CORS errors.
• Confirm there are no critical request failures in Network.
• Confirm no passwords are shown during demo.

---

Test Accounts

Add confirmed test accounts here.

Do not publish real passwords in public documentation.

Role	Email	Password	Notes
Operator	Pending	***	Can create incidents
Supervisor	Pending	***	Can assign technicians and view reports
Technician	Pending	***	Resolves assigned incidents
Manager	Pending	***	Can assign technicians and view reports
Admin	Pending	***	Full or extended access

---

Known Pending Items

• Run full QA with all roles.
• Fix bugs detected during QA.
• Confirm final role rules for manager and admin.
• Confirm final incident visibility rules by role and area.
• Confirm whether technicians can only resolve assigned incidents.
• Confirm whether operators can only see their own incidents or all visible incidents.
• Validate dashboard and reports with enough real data.
• Evaluate whether dashboard should consume /api/reportes/dashboard/ directly.

---

Known Risks

• Render may take longer to respond if the service is asleep.
• Invalid or outdated test credentials can block login validation.
• If there is little real data, dashboard and reports may show limited metrics.
• Backend permissions remain the source of truth even when UI guards hide actions.
• Production requires the correct Vercel environment variables and backend CORS configuration.

---

MVP Approval Criteria

The MVP is ready for demo when:

• Login works in production.
• Operator can create an incident.
• Incident appears in the list.
• Detail view loads correctly.
• Supervisor can assign a technician.
• Assigned technician can resolve the incident.
• Incident is closed/resolved and persisted.
• Dashboard and reports load without critical errors.
• Private routes are protected.
• Navigation respects roles.
• There are no CORS errors.
• Tokens are not stored in localStorage.

---

Impact

OpsCore is expected to improve operational efficiency by:

• Reducing information loss.
• Improving incident traceability.
• Accelerating response times.
• Helping teams identify recurring problems.
• Supporting data-driven decisions.
• Reducing the frequency of critical incidents.

---

Deliverable

Expected delivery: MVP prototype.

The final prototype demonstrates the full incident lifecycle, from mobile reporting to technician assignment, resolution, dashboard tracking, and operational traceability.

---

Team Collaboration

Recommended workflow:

1. Create issues for each feature, fix, or task.
2. Work using feature branches.
3. Open pull requests before merging changes.
4. Review code before merging into the production branch.
5. Keep documentation updated as the project evolves.

Branch Naming

feature/incident-form
feature/dashboard
feature/root-cause-analysis
fix/status-filter
fix/technician-assignment
docs/update-readme

Commit Examples

feat: add mobile incident report form
feat: create incident dashboard layout
fix: update incident status logic
fix: load assignable technicians from dedicated endpoint
docs: update MVP status and QA scope
refactor: improve folder structure

---

About No Country

This project is being developed as part of a No Country simulation, where multidisciplinary teams collaborate to build real-world digital products in a professional environment.