Configure Copilot instructions for repository

.github/copilot-instructions.md

@@ -0,0 +1,181 @@
+# OctoCAT Supply Chain Management System - Copilot Instructions
+
+## Project Overview
+
+This is a demonstration application showcasing GitHub Copilot capabilities. The OctoCAT Supply Chain Management System is a full-stack TypeScript application that manages supply chain operations including products, suppliers, orders, deliveries, and branches.
+
+**Purpose:** Demo/training application to showcase GitHub Copilot, GHAS, and AI-assisted development features.
+
+**Target Audience:** Developers learning about GitHub Copilot capabilities, including Agent Mode, Vision, MCP Server Integration, and custom instructions.
+
+## Tech Stack
+
+### Backend (API)
+- **Language:** TypeScript
+- **Runtime:** Node.js (>=18)
+- **Framework:** Express.js
+- **API Documentation:** Swagger/OpenAPI (swagger-jsdoc, swagger-ui-express)
+- **Testing:** Vitest with Supertest
+- **Build:** TypeScript Compiler (tsc)
+
+### Frontend
+- **Language:** TypeScript
+- **Framework:** React 18+
+- **Build Tool:** Vite
+- **Styling:** Tailwind CSS
+- **Routing:** React Router DOM v7
+- **State Management:** React Query (v3)
+- **HTTP Client:** Axios
+
+### DevOps
+- **Containerization:** Docker/Docker Compose
+- **Package Manager:** npm workspaces
+
+## Project Structure
+
+```
+/
+├── .github/              # GitHub-specific configurations
+│   ├── agents/          # Custom Copilot agents (Chat Mode)
+│   ├── prompts/         # Copilot prompt files for automation
+│   ├── workflows/       # GitHub Actions workflows
+│   └── instructions/    # Path-specific Copilot instructions
+├── api/                 # Backend API workspace
+│   ├── src/
+│   │   ├── index.ts    # Main entry point
+│   │   ├── models/     # Data models with Swagger schemas
+│   │   ├── routes/     # Express routes with Swagger docs
+│   │   └── seedData.ts # Sample data initialization
+│   └── package.json
+├── frontend/            # React frontend workspace
+│   ├── src/
+│   │   ├── components/ # React components (organized by feature)
+│   │   ├── context/    # React context providers
+│   │   └── api/        # API configuration
+│   └── package.json
+├── docs/               # Project documentation
+└── package.json        # Root workspace configuration
+```
+
+## Coding Standards
+
+### General
+- Use TypeScript for all code (strict mode enabled)
+- Use ES6+ features (async/await, arrow functions, destructuring)
+- Prefer functional programming patterns where appropriate
+- Keep files focused and modular (single responsibility)
+- Use meaningful, descriptive variable and function names
+
+### TypeScript
+- Always define interfaces for data structures
+- Use explicit return types for functions
+- Avoid `any` type; use `unknown` if type is truly unknown
+- Use optional chaining (`?.`) and nullish coalescing (`??`)
+
+### API Development (Express.js)
+- Use Swagger/OpenAPI JSDoc comments for all routes and models
+- Follow RESTful conventions:
+  - GET for retrieval
+  - POST for creation
+  - PUT for full updates
+  - PATCH for partial updates
+  - DELETE for removal
+- Structure routes consistently:
+  ```typescript
+  /**
+   * @swagger
+   * /api/resource:
+   *   get:
+   *     summary: Description
+   *     tags: [TagName]
+   *     responses:
+   *       200:
+   *         description: Success response
+   */
+  router.get('/api/resource', (req, res) => { ... });
+  ```
+- Use express.Router() for modular route definitions
+- Enable CORS appropriately for frontend communication
+
+### Frontend Development (React)
+- Use functional components with hooks (no class components)
+- Prefer named exports for components
+- Use React Query for data fetching and caching
+- Implement loading and error states for async operations
+- Use Tailwind CSS utility classes for styling
+- Organize components by feature/entity in subdirectories
+- Use TypeScript interfaces for component props and data structures
+- Implement responsive design patterns
+
+### Testing
+- Use Vitest for all tests
+- Use Supertest for API route testing
+- Include describe/it blocks with clear descriptions
+- Test both success and error cases
+- Mock external dependencies appropriately
+- Reset state between tests using beforeEach/afterEach
+- Run tests with: `npm run test:api` (API) or `npm test` (all workspaces)
+
+### Documentation
+- Use JSDoc comments for functions and complex logic
+- Keep Swagger documentation in sync with API implementation
+- Update README.md when adding new features or changing setup
+- Document non-obvious decisions and workarounds
+
+## Build and Development Commands
+
+### Development
+```bash
+npm install              # Install all workspace dependencies
+npm run dev             # Start both API and frontend in dev mode
+npm run dev:api         # Start only API (port 3000)
+npm run dev:frontend    # Start only frontend (port 5137)
+```
+
+### Building
+```bash
+npm run build           # Build all workspaces
+npm run build --workspace=api       # Build API only
+npm run build --workspace=frontend  # Build frontend only
+```
+
+### Testing
+```bash
+npm run test            # Run all tests
+npm run test:api        # Run API tests (Vitest)
+npm run test:frontend   # Run frontend tests
+```
+
+### Linting
+```bash
+npm run lint            # Lint frontend code (ESLint)
+```
+
+## Data Model
+
+The application follows an entity-relationship model for a supply chain system:
+
+- **Headquarters** (1) → (N) **Branch**
+- **Branch** (1) → (N) **Order**
+- **Order** (1) → (N) **OrderDetail**
+- **OrderDetail** (1) → (N) **OrderDetailDelivery**
+- **OrderDetail** (N) → (1) **Product**
+- **Delivery** (1) → (N) **OrderDetailDelivery**
+- **Supplier** (1) → (N) **Delivery**
+
+See `/api/ERD.png` for visual representation.
+
+## Important Notes
+
+- The API runs on port 3000, frontend on port 5137
+- In Codespaces, set API port visibility to "public" to avoid CORS issues
+- This is a demo application - prioritize clarity and demonstration value over production optimizations
+- The entire project was created using AI and GitHub Copilot
+- Sample data is seeded on API startup for demonstration purposes
+
+## Resources
+
+- [Full Architecture Documentation](./docs/architecture.md)
+- [Build Instructions](./docs/build.md)
+- [Demo Script](./docs/demo-script.md)
+- [API Swagger Documentation](http://localhost:3000/api-docs) (when running)

.github/instructions/API.instructions.md

@@ -0,0 +1,194 @@
+---
+applyTo: 'api/**/*.ts'
+---
+
+# API-Specific Copilot Instructions
+
+These instructions apply specifically to the backend API code in the `/api` directory.
+
+## API Architecture
+
+The API follows a modular Express.js architecture with clear separation of concerns:
+- **Routes** (`src/routes/`): Define HTTP endpoints and request handling
+- **Models** (`src/models/`): Define TypeScript interfaces and Swagger schemas
+- **Main Entry** (`src/index.ts`): Express app configuration and middleware setup
+- **Seed Data** (`src/seedData.ts`): Sample data for demonstration purposes
+
+## Swagger/OpenAPI Documentation
+
+**ALWAYS** include comprehensive Swagger JSDoc comments for:
+
+1. **Models** (`src/models/*.ts`):
+```typescript
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ModelName:
+ *       type: object
+ *       required:
+ *         - requiredField
+ *       properties:
+ *         fieldName:
+ *           type: string
+ *           description: Clear description of the field
+ */
+export interface ModelName {
+  fieldName: string;
+}
+```
+
+2. **Routes** (`src/routes/*.ts`):
+```typescript
+/**
+ * @swagger
+ * /api/resource:
+ *   get:
+ *     summary: Brief summary of what the endpoint does
+ *     tags: [ResourceName]
+ *     responses:
+ *       200:
+ *         description: Success response description
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/ModelName'
+ */
+router.get('/api/resource', (req, res) => { ... });
+```
+
+3. **Path Parameters**:
+```typescript
+/**
+ * @swagger
+ * /api/resource/{id}:
+ *   get:
+ *     summary: Get resource by ID
+ *     tags: [ResourceName]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: integer
+ *         description: Resource identifier
+ */
+```
+
+## RESTful Conventions
+
+- Use plural nouns for resource endpoints (`/api/products`, not `/api/product`)
+- Implement standard HTTP methods:
+  - `GET /api/resources` - List all resources
+  - `GET /api/resources/:id` - Get single resource
+  - `POST /api/resources` - Create new resource
+  - `PUT /api/resources/:id` - Update resource (full replacement)
+  - `DELETE /api/resources/:id` - Delete resource
+- Return appropriate HTTP status codes:
+  - 200 OK - Successful GET, PUT, DELETE
+  - 201 Created - Successful POST
+  - 404 Not Found - Resource doesn't exist
+  - 400 Bad Request - Invalid input
+
+## In-Memory Data Storage
+
+The API uses in-memory arrays for data storage (this is a demo app):
+- Data is stored in module-level variables (e.g., `let products: Product[] = [];`)
+- Data persists only during the API process lifetime
+- Seed data is initialized on startup from `seedData.ts`
+- Use array methods for CRUD operations:
+  - `find()` for single retrieval
+  - `filter()` for multiple retrieval
+  - `push()` for creation
+  - `splice()` or `filter()` for deletion
+  - Direct assignment or `map()` for updates
+
+## Error Handling
+
+- Always validate input parameters
+- Return meaningful error messages
+- Use try-catch for operations that might fail
+- Example:
+```typescript
+if (!id) {
+  return res.status(400).json({ error: 'ID is required' });
+}
+const resource = resources.find(r => r.id === parseInt(id));
+if (!resource) {
+  return res.status(404).json({ error: 'Resource not found' });
+}
+```
+
+## Testing Standards
+
+- Tests live alongside route files (e.g., `branch.test.ts` next to `branch.ts`)
+- Use Vitest and Supertest for API route testing
+- Structure tests with clear describe/it blocks:
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import request from 'supertest';
+import app from '../index';
+
+describe('Resource API', () => {
+  beforeEach(() => {
+    // Reset state if needed
+    resetResourceData();
+  });
+
+  it('should return all resources', async () => {
+    const response = await request(app).get('/api/resources');
+    expect(response.status).toBe(200);
+    expect(response.body).toBeInstanceOf(Array);
+  });
+});
+```
+- Test both successful operations and error cases
+- Use `resetBranchData()` or similar functions to reset in-memory data between tests
+- Run tests with: `npm run test:api`
+
+## CORS Configuration
+
+- CORS is enabled for frontend communication
+- Development frontend typically runs on port 5137
+- In Codespaces, ensure API port visibility is set to "public"
+
+## Common Patterns
+
+### ID Generation
+Use `Math.max(...items.map(i => i.id), 0) + 1` for generating new IDs
+
+### Route Module Export
+Export an Express Router instance:
+```typescript
+import express from 'express';
+const router = express.Router();
+// ... define routes ...
+export default router;
+```
+
+### Importing Routes in Main
+```typescript
+import resourceRoutes from './routes/resource';
+app.use(resourceRoutes);
+```
+
+## Development Workflow
+
+1. Define the model interface with Swagger schema (`src/models/`)
+2. Create route handlers with Swagger docs (`src/routes/`)
+3. Add sample seed data if needed (`src/seedData.ts`)
+4. Write tests for the routes (`src/routes/*.test.ts`)
+5. Run tests: `npm run test:api`
+6. Start dev server: `npm run dev:api`
+7. Verify in Swagger UI: http://localhost:3000/api-docs
+
+## Key Files
+
+- `src/index.ts` - Express app setup, middleware, Swagger configuration
+- `src/routes/*.ts` - Individual resource route handlers
+- `src/models/*.ts` - TypeScript interfaces with Swagger schemas
+- `src/seedData.ts` - Sample data initialization
+- `vitest.config.ts` - Test configuration
+- `tsconfig.json` - TypeScript configuration