|
1 | 1 | # Copilot Instructions |
2 | 2 |
|
3 | | -## Architecture |
| 3 | +## Purpose |
4 | 4 |
|
5 | | -- `backend/app.py` hosts REST (`/api/*`), MCP JSON-RPC (`/mcp`), and LangGraph agent (`/api/agents/run`) on port 5001; new capabilities should use the `@operation` decorator in `backend/operations.py` so all interfaces stay in sync. |
6 | | -- Business logic lives in service modules: `tasks.py` (TaskService), `tickets.py` (ticket models + SLA calculations); keep services as the single source of truth. |
7 | | -- The React side is feature-first: `frontend/src/App.jsx` switches tabs via React Router; each folder under `frontend/src/features` owns its state, calculations, and FluentUI layout. |
8 | | -- All network calls go through `frontend/src/services/api.js`; localStorage helpers live in separate modules like `reminderStorage.js`. |
| 5 | +This repository is a **learning environment** for processing and visualizing CSV ticket data using Copilot. |
9 | 6 |
|
10 | | -## Backend Patterns |
| 7 | +## Scope Boundaries |
11 | 8 |
|
12 | | -- Define operations with `@operation` (see `op_create_task`, `op_get_task`): annotate parameters with Pydantic models or enums so MCP schemas and REST validation are generated automatically, then build thin Quart wrappers that only handle HTTP concerns. |
13 | | -- Keep methods like `TaskService.create_task` and `TaskService.update_task` “deep”: they already validate, mutate `_tasks_db`, and return `Task` models, so avoid splitting them into tiny helpers or duplicating validation elsewhere. |
14 | | -- Use the provided Pydantic models (`TaskCreate`, `TaskUpdate`, `TaskStats`, `TaskFilter`) for all inputs/outputs; MCP tooling and REST serializers expect `.model_dump()` objects with these exact field names (`created_at`, `completed`, etc.). |
15 | | -- The SSE endpoint `time_stream` streams `{"time","date","timestamp"}` JSON strings; if you change its shape, also update `connectToTimeStream` consumers and the Dashboard expectations. |
| 9 | +**Do:** |
16 | 10 |
|
17 | | -## Frontend Patterns |
| 11 | +- Work with `csv/data.csv` and related parsing logic (`backend/csv_data.py`) |
| 12 | +- Write/adjust small, focused Python scripts or notebooks for data exploration (pandas, matplotlib, seaborn, plotly) |
| 13 | +- Compute summaries, statistics, filters, aggregations on ticket data |
| 14 | +- Propose visualizations and queries to understand ticket patterns |
| 15 | +- Help interpret CSV schema and column mappings |
18 | 16 |
|
19 | | -- Feature components isolate **calculations** (pure helpers like `getTaskStats`), **actions** (API calls, event handlers), and **data** (React state) in that order; preserve that structure when extending `TaskList` or `Dashboard`. |
20 | | -- Stick to FluentUI v9 primitives with `makeStyles`/`tokens`; prefer adjusting the `useStyles` definitions over inline styles to maintain theming consistency. |
21 | | -- Always go through `frontend/src/services/api.js` (`fetchJSON`, `createTask`, `updateTask`, etc.); components expect rejected promises to carry friendly `Error.message`, so don’t bypass these helpers. |
22 | | -- Task UI and tests rely on deterministic `data-testid` attributes (`task-menu-${id}`, `filter-completed`, etc.); keep them stable or update the Playwright suite alongside UI changes. |
23 | | -- Real-time widgets follow the `connectToTimeStream` contract (subscribe in `useEffect`, capture cleanup function, surface errors via component state); reuse that approach for any new SSE sources. |
| 17 | +**Do NOT:** |
24 | 18 |
|
25 | | -## Workflows |
| 19 | +- Change backend architecture (`backend/app.py`, `operations.py`, decorators) |
| 20 | +- Modify Pydantic models (`tickets.py`, `tasks.py`) or core services |
| 21 | +- Alter REST/MCP endpoints, React frontend structure, or tests |
| 22 | +- Touch `UNIFIED_ARCHITECTURE.md`, `README.md`, or Playwright tests |
26 | 23 |
|
27 | | -- One-time setup: run `./setup.sh` from the repo root to create the repo-level `.venv`, install frontend deps, and provision Playwright browsers. |
28 | | -- Dev loop: `source .venv/bin/activate && cd backend && python app.py` (serves on 5001) plus `cd frontend && npm run dev`; `./start-dev.sh` or the VS Code “Full Stack: Backend + Frontend” launch config will start both for you. |
29 | | -- MCP testing uses JSON-RPC POSTs to `http://localhost:5001/mcp` (`tools/list`, `tools/call`); no extra process is required because the Quart server already exposes it. |
| 24 | +## CSV Data Structure |
30 | 25 |
|
31 | | -## Testing |
| 26 | +Primary source: `csv/data.csv` (BMC Remedy/ITSM export). |
| 27 | +Key columns: |
32 | 28 |
|
33 | | -- E2E coverage lives in `tests/e2e/app.spec.js`; from the repo root run `npm run test:e2e` (`:ui` for interactive, `:report` to inspect results). Start both servers first to avoid cold-start delays. |
34 | | -- The suite assumes sample tasks exist (created by `TaskService.initialize_sample_data()`), tabs are labeled via `data-testid`, and SSE data matches the backend format; keep those invariants or update the tests deliberately. |
35 | | -- For deterministic assertions, prefer editing helpers like `waitForAppToLoad` or the shared selector strings instead of scattering hard-coded waits. |
| 29 | +- Identifiers: `Entry ID`, `Incident ID*+`, `Corporate ID` |
| 30 | +- Summary: `Summary*`, `Notes`, `Resolution` |
| 31 | +- Status/Priority: `Status*`, `Priority*`, `Urgency*`, `Impact*` |
| 32 | +- Assignment: `Assignee+`, `Assigned Group*+`, `Owner Group+` |
| 33 | +- Requester: `Full Name`, `First Name+`, `Last Name+`, `Internet E-mail` |
| 34 | +- Location: `City`, `Country`, `Site ID`, `Company` |
| 35 | +- Timestamps: `Reported Date+`, `Last Modified Date`, `Closed Date` |
| 36 | +- Categories: `Operational Categorization Tier 1+/2/3`, `Product Categorization Tier 1/2/3` |
| 37 | + |
| 38 | +Reference implementation: `backend/csv_data.py` (column mapping, status/priority mapping, date parsing). |
| 39 | + |
| 40 | +## Working with the Data |
| 41 | + |
| 42 | +- Load: `pd.read_csv("csv/data.csv", encoding="latin-1")` |
| 43 | +- Dates: parse `DD.MM.YYYY HH:MM:SS` (e.g., `22.10.2025 11:53:33`) |
| 44 | +- Status mapping: New, Assigned, In Progress, Pending, Resolved, Closed, Cancelled |
| 45 | +- Priority mapping: 1-Critical, 2-High, 3-Medium, 4-Low |
| 46 | +- Prefer notebooks for exploration; keep scripts small and focused |
36 | 47 |
|
37 | 48 | ## Conventions |
38 | 49 |
|
39 | | -- Follow “Grokking Simplicity”: keep actions (I/O) in services or event handlers, calculations pure (formatting, stats), and data as plain objects/React state; this is enforced heavily in docs and existing code. |
40 | | -- Follow “A Philosophy of Software Design”: favor deep modules (e.g., extend `TaskService` instead of sprinkling logic across routes/components) and hide complexity behind simple interfaces. |
41 | | -- When you touch the architecture (operation decorators, unified REST/MCP flow, feature structure), update `README.md` and `UNIFIED_ARCHITECTURE.md` so future agents inherit the correct mental model. |
| 50 | +- Follow “Grokking Simplicity”: separate data (CSV), calculations (pure), actions (I/O) |
| 51 | +- Keep changes minimal, targeted, and reversible |
| 52 | +- No broad refactors; prioritize clarity for learners |
| 53 | +- Document findings inline (markdown cells/comments) |
0 commit comments