Refactor code structure for improved readability and maintainability

.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# Copilot Workspace Instructions
+
+Purpose
+- Help Copilot-style agents and contributors be productive and safe in this repository.
+- Surface where to find authoritative docs and which conventions to follow.
+
+Principles
+- Link, don't embed: prefer linking to existing docs in `docs/`, `CONTRIBUTING.md`, or `README.md` rather than duplicating content.
+- Minimize blast radius: make minimal, focused changes and explain rationale in PRs.
+- Ask clarifying questions before large or ambiguous changes.
+
+What the agent is allowed to do
+- Suggest edits, create focused patches, and propose new files following repo style.
+- Use `apply_patch` for file edits; create new files only when necessary.
+- Run or suggest commands to run tests locally, but do not push or merge without human approval.
+
+Conventions & expectations
+- Follow existing code style and directory boundaries (`backend/` for Flask/Python, `frontend/` for Vite/TypeScript).
+- When changing behavior, run tests and list the commands to reproduce the failure/fix.
+- Keep PRs small and target a single logical change.
+
+Key files & links (authoritative sources)
+- README: [README.md](README.md#L1)
+- Contribution & tests: [CONTRIBUTING.md](CONTRIBUTING.md#L1)
+- Docker & run commands: [docs/Docker-Commands-Guide.md](docs/Docker-Commands-Guide.md#L1)
+- Backend entry & requirements: [backend/requirements.txt](backend/requirements.txt#L1), [backend/Dockerfile](backend/Dockerfile#L1)
+- Frontend scripts: [frontend/package.json](frontend/package.json#L1), [frontend/Dockerfile](frontend/Dockerfile#L1)
+- Compose files: [docker-compose.yml](docker-compose.yml#L1), [docker-compose.prod.yml](docker-compose.prod.yml#L1)
+- Deployment scripts: [scripts/deploy.sh](scripts/deploy.sh#L1)
+
+Common build & test commands
+- Backend tests (project root):
+```
+cd backend && python -m pytest tests/ -q
+```
+- Frontend dev & tests:
+```
+cd frontend && npm install
+cd frontend && npm run dev
+cd frontend && npx vitest run
+```
+- Dev compose (full stack):
+```
+docker compose up --build
+```
+- Prod deploy (refer to `scripts/deploy.sh`):
+```
+./scripts/deploy.sh
+```
+
+Anti-patterns (avoid)
+- Don't invent architectural decisions or rewrite large areas without explicit approval.
+- Don't add secrets, large binary files, or unrelated formatting changes.
+- Don't run destructive commands or modify CI/CD configuration without coordination.
+
+Agent prompts & examples
+- "Create a small Flask route in `backend/app/routes` that returns health JSON and add a unit test."
+- "Refactor the image compression service to extract a helper; update callers and tests." 
+- "List the exact commands I should run to reproduce the failing tests for `backend/tests/test_pdf_service.py`."
+
+Suggested follow-ups (agent customizations)
+- `create-agent:backend` — focused on Python/Flask edits, runs `pytest`, and knows `backend/` structure.
+- `create-agent:frontend` — focused on Vite/TypeScript, runs `vitest`, and uses `npm` scripts.
+- `create-agent:ci` — analyzes `docker-compose.yml` and `scripts/deploy.sh`, suggests CI checks and smoke tests.
+
+If you want, I can:
+- Open a draft PR with this file, or
+- Expand the file with more precise command snippets and per-service README links.
+
+---
+Generated by a workspace bootstrap; iterate as needed.