# SearchUs Full Platform Specification & LLM Reference

This document provides a comprehensive text reference for Large Language Models (LLMs), AI crawlers, and automated coding agents interacting with the SearchUs codebase and platform.

---

## 1. System Architecture

SearchUs is built as a TypeScript monorepo using `pnpm`:

- **Frontend (`apps/web`)**: Next.js 16 (App Router), React 19, Tailwind CSS, Lucide Icons, React Query, Zustand, Hook Form, Zod.
- **Backend (`apps/server`)**: Node.js, Express 5, Prisma ORM, PostgreSQL (pgvector / pg_trgm indexes), JWT Authentication.
- **Shared (`apps/shared`)**: Common TypeScript types, validation schemas, and constant definitions.

---

## 2. Job Search Query Schema

### Query Parameters (`GET /api/v1/job`)
- `search` / `query` (string): Natural language or job title keyword (e.g. "React Developer Kuala Lumpur").
- `location` (string): State or region in Malaysia (e.g. "Kuala Lumpur", "Selangor", "Penang", "Johor", "Remote / International").
- `jobType` (string): Comma-separated list (`full-time`, `part-time`, `contract`, `internship`, `freelance`).
- `jobMode` (string): Comma-separated list (`on-site`, `hybrid`, `remote`).
- `minRate` (number): Minimum salary expectation in MYR (RM).
- `maxRate` (number): Maximum salary budget in MYR (RM).
- `page` (number): Page number (default: `1`).
- `size` (number): Number of items per page (default: `10`).
- `sort` (string): Ordering (`createdAt:desc`, `createdAt:asc`).

---

## 3. AI Match Rating Engine

Jobs are evaluated against candidate profile criteria using a 3-tier match score:

1. **Excellent Match (90% - 100%)**:
   - Skillset overlaps with job requirements.
   - Preferred location matches job location.
   - Salary expectation within job salary range.
2. **Good Match (75% - 89%)**:
   - Core qualification met; minor experience gap (e.g., 2 years vs 3 years required).
3. **Possible Match (< 75%)**:
   - Alternate background or partial skill match.

---

## 4. Candidate AI Assistant Workflow

The platform provides 4 built-in candidate AI tools:

1. **Role Compatibility Analysis (`suitable`)**:
   - Evaluates skills, education, work arrangement, and expected salary range.
2. **Resume & CV Tailoring (`tailor-cv`)**:
   - Extracts ATS keywords and recommends targeted experience bullet points.
3. **Cover Letter Generator (`cover-letter`)**:
   - Generates a customized cover letter draft pre-filled with candidate and employer information.
4. **Interview Preparation Kit (`prep-interview`)**:
   - Generates position-specific technical and behavioral questions formatted using the STAR method.

---

## 5. Job Application Schema

### Data Payload (`POST /api/v1/job-application`)
```json
{
  "jobId": "string",
  "phone": "+60123456789",
  "applyReason": "Candidate application pitch / rationale string",
  "documents_url": {
    "cv": "https://... or upload path",
    "portfolio": "https://... or upload path"
  }
}
```

---

## 6. Robots & AI Crawling Directives
- Public listings and company profile pages allow unrestricted indexing.
- Search engine and LLM bots should refer to `/sitemap.xml` and `/llms.txt`.