doc: new documents

README.md

@@ -0,0 +1,123 @@
+# ResumeLens
+
+ResumeLens is a web app that grades a resume against a job description.
+
+- Backend: Go HTTP API (`/api/analyze`)
+- Frontend: React + Vite
+- AI provider: OpenAI (server-side only)
+
+## What the project does
+
+1. Accepts a PDF resume upload and job description text.
+2. Extracts text from the PDF on the backend.
+3. Sends resume text + job description to the LLM.
+4. Returns structured JSON with score and feedback.
+
+## Tech stack
+
+- Go 1.25.x
+- Node 20+
+- React 19 + Vite 7
+- Docker + Docker Compose (optional)
+
+## Prerequisites
+
+- `go` installed
+- `node` and `npm` installed
+- `OPENAI_API_KEY` set for real analysis calls
+
+Example:
+
+```bash
+export OPENAI_API_KEY="your_key_here"
+```
+
+## Run locally
+
+### 1) Start backend API
+
+From repo root:
+
+```bash
+go run ./cmd/server
+```
+
+Backend listens on `http://localhost:3000`.
+
+### 2) Start frontend
+
+In another terminal:
+
+```bash
+cd web
+npm ci
+npm run dev
+```
+
+Frontend runs on Vite default port (usually `http://localhost:5173`).
+
+By default in development, frontend calls backend at `http://localhost:3000`.
+
+## Run with Docker Compose
+
+From repo root:
+
+```bash
+docker compose up --build
+```
+
+- Frontend is exposed at `http://localhost:3005`
+- Frontend proxies `/api` traffic to the backend container
+- Backend uses values from root `.env`
+
+## API contract
+
+`POST /api/analyze` with `multipart/form-data`:
+
+- `resume`: PDF file
+- `job_description`: plain text
+
+Returns JSON analysis result.
+
+Notes:
+
+- Request size is capped at 10 MB.
+- Rate limit is 10 analyze requests per hour per IP.
+
+## Tests
+
+Run all default Go tests:
+
+```bash
+go test ./...
+```
+
+Run tests with race detector:
+
+```bash
+go test -race ./...
+```
+
+There is an opt-in live OpenAI consistency test. It is skipped by default.
+
+```bash
+RUN_LIVE_OPENAI_TESTS=1 OPENAI_API_KEY="your_key_here" go test ./internal/services -run TestCallLLM_Live_ScoreConsistencyPlusMinus10 -v
+```
+
+Frontend checks:
+
+```bash
+cd web
+npm run lint
+npm run build
+```
+
+## Handoff notes
+
+- Verification strategy doc: `doc/verification-strategy.md`
+- Main backend entrypoint: `cmd/server/main.go`
+- API route mount: `internal/api/routes.go`
+- Analyze handler: `internal/handlers/analyze.go`
+- LLM service: `internal/services/analyzer.go`
+
+If analysis fails in a fresh environment, first check that `OPENAI_API_KEY` is set in the backend process environment.

doc/verification-strategy.md

@@ -0,0 +1,192 @@
+# Verification Strategy and Test Implementation
+
+**Course:** SE 300 Software Engineering Practices  
+**Term:** Spring 2026  
+**Project:** _Resume Lens_  
+
+## 1) Verification Philosophy
+
+Our verification strategy is designed to show that the software is:
+
+- **Correct**: Implements the requirements defined in the SRD/SDD.
+- **Reliable**: Behaves consistently under expected and edge-case conditions.
+- **Safe in process**: Developed using disciplined engineering practices (reviews, traceability, repeatable tests).
+
+To achieve this, we use a combination of:
+
+- **Testing** (unit, integration, and system-level)
+- **Reviews** (design and code reviews)
+- **Analysis** (static checks and traceability analysis)
+
+This layered approach helps us detect defects early, validate behavior continuously, and provide objective evidence of quality.
+
+## 2) Verification Approach Overview
+
+We combine **black-box** and **white-box** techniques:
+
+- **Black-box testing** validates external behavior against requirements without relying on internal code structure.
+- **White-box testing** validates internal logic paths, branches, and error handling.
+
+Testing is organized by level:
+
+- **Unit Testing**: verifies individual functions/classes/modules.
+- **Integration Testing**: verifies interactions between modules/interfaces.
+- **System Testing**: verifies end-to-end behavior from a user perspective.
+
+Techniques used include:
+
+- **Boundary Value Analysis**
+- **Equivalence Partitioning**
+- **Negative/Error-condition testing**
+- **Regression testing** after changes
+
+## 3) Test Case and Test Procedure Structure (1:M)
+
+We follow a 1:M hierarchy:
+
+- A **Test Case (TC)** targets one behavior/requirement area.
+- Each TC has one or more **Test Procedures (TPs)** that define concrete execution scenarios.
+
+Example:
+
+- **TC-INPUT-01**: Validate user input handling
+  - **TP-INPUT-01A**: Valid input accepted
+  - **TP-INPUT-01B**: Empty input rejected
+  - **TP-INPUT-01C**: Over-length input rejected
+  - **TP-INPUT-01D**: Invalid characters handled safely
+
+## 4) Requirement Traceability
+
+Every test case maps to one or more requirements from the SRD/SDD, and code blocks include trace tags tied to LLD/HLD tags.
+
+Traceability chain:
+
+`Requirement ID -> Design Tag (LLD/HLD) -> Code Trace Tag -> Test Case ID -> Test Procedure ID -> Result Evidence`
+
+This ensures we can prove coverage from requirements through implementation and verification.
+
+## 5) Test Artifacts and Implementation
+
+For each test we maintain:
+
+- **Test Case ID and objective**
+- **Mapped requirement/design tags**
+- **Preconditions**
+- **Inputs/test data**
+- **Steps**
+- **Expected result**
+- **Actual result**
+- **Pass/Fail status**
+- **Execution date and tester**
+- **Evidence** (logs, screenshots, reports)
+
+Execution is repeatable using the team's build/test commands (e.g., CI or local scripts), enabling consistent regression checks.
+
+## 6) Planned Test Cases (Summary)
+
+> Replace IDs/content below with your project-specific items.
+
+### TC-FUNC-01: Core Feature Behavior
+
+- **Purpose**: Verify primary functional requirement(s).
+- **Type**: Black-box, system test.
+- **Procedures**:
+  - TP-FUNC-01A normal flow
+  - TP-FUNC-01B alternate valid flow
+  - TP-FUNC-01C invalid input flow
+
+### TC-BOUND-02: Boundary Conditions
+
+- **Purpose**: Verify behavior at min/max/edge values.
+- **Type**: Black-box + white-box, unit/integration.
+- **Procedures**:
+  - TP-BOUND-02A minimum boundary
+  - TP-BOUND-02B maximum boundary
+  - TP-BOUND-02C just-below/just-above boundary
+
+### TC-ERROR-03: Error Handling and Recovery
+
+- **Purpose**: Verify robustness under invalid states/failures.
+- **Type**: White-box + integration.
+- **Procedures**:
+  - TP-ERROR-03A null/empty references
+  - TP-ERROR-03B invalid format/type
+  - TP-ERROR-03C dependency/service unavailable
+
+### TC-INT-04: Module Interaction
+
+- **Purpose**: Verify data flow and contract compliance across components.
+- **Type**: Integration.
+- **Procedures**:
+  - TP-INT-04A successful data exchange
+  - TP-INT-04B malformed payload handling
+  - TP-INT-04C timeout/retry behavior (if applicable)
+
+### TC-REG-05: Regression Suite
+
+- **Purpose**: Ensure prior functionality remains intact after changes.
+- **Type**: Automated regression (unit/integration/system mix).
+- **Procedures**:
+  - TP-REG-05A smoke tests
+  - TP-REG-05B critical-path revalidation
+
+## 7) Reviews and Analysis Procedures
+
+### 7.1 Design/Artifact Reviews
+
+- Review SRD/SDD/LLD consistency before implementation.
+- Confirm each requirement is testable and traceable.
+
+### 7.2 Code Reviews
+
+- Peer review for all significant changes.
+- Checklist includes:
+  - requirement trace tag present
+  - correctness and readability
+  - error handling
+  - test coverage impact
+  - no unintended side effects
+
+### 7.3 Static Analysis
+
+- Use compiler/linter/static tools to detect:
+  - syntax/type issues
+  - dead code
+  - obvious anti-patterns
+  - potential reliability concerns
+
+## 8) Entry/Exit Criteria
+
+**Entry criteria (before running verification):**
+
+- Build succeeds.
+- Required environment/dependencies available.
+- Relevant test data prepared.
+- Requirement-to-test mappings updated.
+
+**Exit criteria (verification complete):**
+
+- All planned TCs executed.
+- Critical tests pass.
+- Failed tests triaged with disposition.
+- Traceability matrix updated.
+- Evidence package assembled.
+
+## 9) Deliverable Contents (Verification Package)
+
+The verification package includes:
+
+- This verification philosophy and strategy document.
+- Full list of test cases and test procedures.
+- Review and analysis procedure descriptions.
+- Requirement/design/code/test traceability matrix.
+- Test execution evidence and pass/fail report.
+
+## 10) Demo Readiness (In-Class)
+
+For the in-class demo, we will prepare:
+
+- A brief walkthrough of core features.
+- A short explanation of verification approach.
+- Selected test evidence demonstrating correctness and reliability.
+- Q&A support materials (requirements map, traceability, test summary).

web/README.md

@@ -1,73 +0,0 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```