# SuperDocs Full Documentation

> This file contains the full content of key documentation pages hosted on SuperDocs.
> Use this for comprehensive context about available technical documentation.

---

## Admin Dashboard Management

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/admin-dashboard-management-1b840d56

The Admin Dashboard is the central hub for recruitment officers to manage the lifecycle of applicants. Built with a focus on efficiency, it provides a comprehensive overview of candidate profiles, automated resume analysis, and communication tools.

## Accessing the Dashboard

To access administrative features, navigate to `/admin/login`. The system uses secure authentication via Supabase. Once authenticated, you will be redirected to the **Admin Dashboard**.

> **Note:** Access is restricted to authorized personnel. If you are not logged in, you will be automatically redirected to the login page when attempting to access dashboard routes.

## Applicant Overview

The main dashboard presents a tabular view of all submitted applications. This view is designed for rapid screening and includes:

*   **Candidate Identity:** Name and contact information.
*   **Academic Background:** Highest degree obtained.
*   **Professional Context:** Years of experience and preferred Japanese language course.
*   **ATS Score:** A keyword match score calculated during the resume parsing process.
*   **Current Status:** Real-time application status (e.g., Pending, Reviewed).

## Reviewing Candidate Details

Clicking on an individual applicant opens the **Applicant Detail** page. This view provides a deep dive into the candidate's qualifications and the automated analysis performed by the system.

### Resume Analysis (ATS Scoring)
The system automatically parses uploaded PDF resumes to identify key competencies.
*   **Keyword Match Score:** A percentage-based score (0–100%) indicating how well the candidate's CV aligns with predefined job and language keywords.
*   **Matched Keywords:** A visual tag cloud showing which specific technical skills (e.g., React, Python, SQL) or language proficiencies (e.g., JLPT N2, Conversational Japanese) were found.
*   **Extracted Text:** A preview of the raw text extracted from the CV for quick verification without downloading the file.

### Resume Management
While the dashboard provides a text preview, you can download the original PDF at any time:
1.  Navigate to the **Applicant Detail** page.
2.  Click the **Download CV** button.
3.  The file will be saved locally using the naming convention: `FullName_CV.pdf`.

## Managing Application Status

The ATS supports a structured workflow for candidate evaluation. You can update an applicant's status using the dropdown menu in the detail view.

### Status Types
*   **Pending:** The default state for new submissions.
*   **Reviewed:** The application has been opened and the resume analysis has been checked.
*   **Accepted:** The candidate has passed the initial screening.
*   **Rejected:** The candidate does not meet the current requirements.

### Automated Notifications
When you update a status, the system triggers an automated email notification to the candidate via the **Resend** integration. 

| Status | Notification Action |
| :--- | :--- |
| **Reviewed** | Notifies the candidate that their application is under active review. |
| **Accepted** | Sends a congratulatory email with information regarding next steps. |
| **Rejected** | Sends a polite update regarding the decision. |

> **Success Confirmation:** Upon a successful status change, a toast notification will appear. If the automated email fails to send, the system will alert you, though the status change in the database will remain.

## Exporting Candidate Data

For external reporting or offline analysis, the system allows you to export applicant data.

*   **Format:** CSV (Comma Separated Values).
*   **Included Fields:** Full name, Email, Experience, Degree, Preferred Course, ATS Score, and current Status.
*   **Usage:** Use the **Export to CSV** button on the main dashboard to generate a report of all current applicants in the system.

---

## Applicant Submission Flow

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/applicant-submission-flow-9c29f431

The applicant submission flow is designed to be a streamlined, user-friendly experience that captures essential candidate information while performing automated resume analysis in the background.

## Application Form Overview

The primary entry point for candidates is the application form located at the root path (`/`). This form is built using **React Hook Form** and **Zod** for robust client-side validation, ensuring that only complete and correctly formatted data reaches the database.

### Data Fields and Validation

Applicants are required to provide the following information:

| Field | Type | Validation Rules |
| :--- | :--- | :--- |
| **Full Name** | Text | 2–100 characters |
| **Date of Birth** | Date | Required |
| **Email Address** | Email | Valid format, max 255 characters |
| **Highest Degree** | Select | Must select from predefined list (e.g., Bachelor's, Master's) |
| **Years of Experience** | Number | Range: 0 to 50 years |
| **Preferred Course** | Select | Must select from available JLPT or Business courses |
| **Comments** | Textarea | Optional, max 1000 characters |
| **Resume (CV)** | File | **PDF only**, maximum size **5MB** |

## Submission Step-by-Step

### 1. Data Entry and Validation
As the user fills out the form, the system provides real-time feedback. If an invalid email is entered or a required field is skipped, the `FormMessage` components (via shadcn-ui) display specific error messages.

### 2. Resume Upload
The application specifically requests a PDF version of the candidate's CV. Upon selection, the system validates:
*   **MIME Type:** Must be `application/pdf`.
*   **File Size:** Must not exceed the 5MB limit defined in `MAX_FILE_SIZE`.

### 3. Data Processing
When the user clicks **"Submit Application"**, the following sequence occurs:
1.  **File Storage:** The PDF is uploaded to the Supabase `cvs` storage bucket with a unique timestamped filename.
2.  **Database Record:** A new entry is created in the `applicants` table containing the personal details and the path to the uploaded file.
3.  **Status Initialization:** The application status is automatically set to `pending`.

### 4. Automated Resume Parsing
Immediately after the database record is created, the system triggers an edge function:

```typescript
// Background CV parsing trigger
supabase.functions.invoke("parse-cv", {
  body: {
    applicantId: applicantData.id,
    cvFilePath: fileName,
  },
})
```

This process is **non-blocking**; the user does not have to wait for the parsing to finish to see the success message. The edge function extracts text from the PDF and performs keyword matching against a library of technical and linguistic terms (e.g., "JLPT N2", "React", "Python").

## Post-Submission Experience

Upon successful submission, the UI transitions to a confirmation state:
*   **Success Screen:** A high-visibility confirmation page (using the `CheckCircle` icon and `animate-scale-in` animation) informs the candidate that their application was received.
*   **Background Updates:** Once the background `parse-cv` function completes, the applicant's record in the dashboard will be updated with a **Keyword Match Score** and a list of **Matched Keywords**, ready for administrative review.
*   **Notifications:** If configured, the system prepares the entry for the `send-status-notification` workflow, which administrators can trigger later during the review process.

---

## Build & Deployment Workflow

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/build-deployment-workflow-111b2ca7

## Build & Deployment Workflow

This section provides a step-by-step guide on how to build the Japanese ATS application for production and deploy its components to the respective cloud environments.

### Prerequisites

Before starting the build and deployment process, ensure you have the following installed and configured:

*   **Node.js** (v18.0.0 or higher)
*   **npm** or **pnpm**
*   **Supabase CLI**: Required for deploying Edge Functions.
*   **A Supabase Project**: Active project with Database, Storage, and Auth enabled.
*   **Resend API Key**: For handling automated email notifications.

---

### 1. Environment Configuration

The application requires specific environment variables to communicate with Supabase and Resend.

#### Frontend (.env)
Create a `.env` file in the root directory for the Vite build:

```bash
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
```

#### Supabase Edge Functions (Secrets)
The Edge Functions require sensitive keys that must be set as Supabase secrets. Run the following commands using the Supabase CLI:

```bash
# Set the Resend API Key for email notifications
supabase secrets set RESEND_API_KEY=your_resend_api_key

# The system also relies on internal Supabase environment variables 
# (SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY) which are usually 
# available by default in the Edge Function environment.
```

---

### 2. Building the Frontend

The project uses **Vite** as the build tool. This generates a highly optimized static bundle in the `dist/` folder.

```bash
# Install dependencies
npm install

# Generate production build
npm run build
```

The resulting `dist` folder can be hosted on any static hosting provider such as Vercel, Netlify, or GitHub Pages.

---

### 3. Deploying Supabase Edge Functions

This project utilizes two critical Edge Functions: `parse-cv` (for PDF text extraction and keyword matching) and `send-status-notification` (for Resend email integration).

1.  **Login to Supabase CLI:**
    ```bash
    supabase login
    ```
2.  **Link your project:**
    ```bash
    # Get your project ref from your Supabase dashboard settings
    supabase link --project-ref your-project-id
    ```
3.  **Deploy Functions:**
    ```bash
    # Deploy all functions
    supabase functions deploy parse-cv
    supabase functions deploy send-status-notification
    ```

---

### 4. Infrastructure Requirements

For the system to function correctly after deployment, ensure the following are configured in your Supabase project:

#### Storage Bucket
*   Create a bucket named **`cvs`**.
*   **Policies:** 
    *   Authenticated users should have `INSERT` and `SELECT` access to their own files.
    *   Admins (or the service role) must have `SELECT` access to download and parse the PDFs.

#### Database Schema
Ensure your database has the `applicants` table and the `application_status` enum defined. Based on the project types, the table must include:
*   `cv_file_path`: (text) The path to the file in the storage bucket.
*   `status`: (enum) `pending`, `reviewed`, `accepted`, `rejected`.
*   `keyword_match_score`: (number) Updated automatically by the `parse-cv` function.

---

### 5. Deployment Checklist

| Component | Target | Command / Action |
| :--- | :--- | :--- |
| **Frontend** | Vercel / Netlify / Static Host | `npm run build` & upload `dist/` |
| **Database** | Supabase DB | Run SQL migrations if schema changes. |
| **Edge Functions** | Supabase Edge | `supabase functions deploy [name]` |
| **Auth** | Supabase Auth | Enable Email/Password provider. |
| **Storage** | Supabase Storage | Ensure "cvs" bucket exists. |
| **Secrets** | Supabase Dashboard | Verify `RESEND_API_KEY` is set. |

### Local Development vs. Production
While developing locally, the application uses the Vite development server (`npm run dev`). However, keyword matching and email notifications will only work if your local environment can reach the deployed Supabase Edge Functions or if you run them locally via `supabase functions serve`.

---

## CV Parsing & Extraction

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/cv-parsing-extraction-af90bcb8

## Overview

The CV Parsing & Extraction system automates the process of reading uploaded resumes and identifying candidate strengths. By leveraging asynchronous background processing, the system extracts raw text from PDF files and matches them against industry-standard keywords, providing administrators with an immediate "Match Score" for every application.

## The Parsing Workflow

The extraction process is triggered automatically upon form submission. The workflow follows these steps:

1.  **Storage:** The applicant's PDF is uploaded to the Supabase `cvs` storage bucket.
2.  **Trigger:** The frontend invokes the `parse-cv` Edge Function with the file path and applicant ID.
3.  **Extraction:** The Edge Function uses `pdfjs-dist` to parse the PDF layers and compile raw text.
4.  **Analysis:** The system scans the text for specific job-related keywords.
5.  **Persistence:** The extracted text, matched keywords, and final match score are saved back to the `applicants` table in the database.

## Edge Function: `parse-cv`

The core logic resides in a Supabase Edge Function. This allows the heavy lifting of PDF processing to happen off the main browser thread, ensuring a smooth user experience for the applicant.

### API Interface

To manually trigger or integrate the parser, use the following interface:

**Endpoint:** `parse-cv`  
**Method:** `POST`

**Request Body:**
```typescript
{
  applicantId: string;   // The UUID of the applicant in the database
  cvFilePath: string;    // The path to the file in the 'cvs' storage bucket
  customKeywords?: string[]; // Optional: additional keywords to look for
}
```

**Example Usage:**
```typescript
const { data, error } = await supabase.functions.invoke("parse-cv", {
  body: {
    applicantId: "123-abc",
    cvFilePath: "171589200-resume.pdf",
  },
});
```

## Keyword Matching & Scoring

The system evaluates resumes based on a predefined library of keywords relevant to Japanese language proficiency and technical roles.

### Matching Logic
*   **Word Boundary Detection:** The parser uses regular expressions to ensure keywords are matched as whole words (e.g., matching "Java" but not "Javascript" unless "Javascript" is also a keyword).
*   **Case Insensitivity:** Matches are found regardless of how the candidate capitalized the text.
*   **Score Calculation:** The system grants **10 points per unique keyword match**, capped at a maximum score of **100%**.

### Supported Categories
The analyzer currently looks for:
*   **Japanese Proficiency:** JLPT levels (N1, N2, N3, N4, N5) and language skills.
*   **Tech Stack:** Programming languages (Python, JavaScript, Go), Frameworks (React, Node.js), and Databases.
*   **Infrastructure:** Cloud providers (AWS, Azure, GCP) and DevOps tools (Docker, Kubernetes).
*   **Soft Skills:** Leadership, communication, and project management.

## Administrator View

Once the parsing is complete, the results are available in the **Applicant Detail** page within the Admin Module.

*   **Match Score:** Displayed as a visual percentage to help prioritize candidates.
*   **Matched Keywords:** A list of tags showing exactly which required skills were found in the resume.
*   **Extracted Text:** The raw text output from the PDF is stored and viewable, allowing administrators to search through the resume content without downloading the file.

---

## Database Schema & Types

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/database-schema-types-2bfe9e34

This section provides a technical overview of the data architecture for the Japanese ATS. The system utilizes **Supabase (PostgreSQL)** for data storage and provides full TypeScript definitions for the database schema to ensure type safety across the frontend and Edge Functions.

## Database Schema

The core of the application resides in the `applicants` table, which stores candidate information, resume metadata, and automated screening results.

### The `applicants` Table

This table tracks the lifecycle of an application, from the initial submission to the automated keyword matching process.

| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | `uuid` | Primary key (unique identifier). |
| `full_name` | `text` | The legal name of the applicant. |
| `email` | `text` | Contact email address for notifications. |
| `date_of_birth` | `date` | Applicant's date of birth. |
| `highest_degree` | `text` | Education level (e.g., Bachelor's, Master's). |
| `years_of_experience`| `number` | Total years of relevant professional experience. |
| `preferred_course` | `text` | The specific JLPT or Japanese course applied for. |
| `cv_file_path` | `text` | The path to the PDF file in Supabase Storage (`cvs` bucket). |
| `cv_extracted_text` | `text` | Raw text extracted from the PDF during background parsing. |
| `keyword_match_score`| `number` | Calculated score (0-100) based on keyword matching. |
| `matched_keywords` | `text[]` | Array of specific keywords found within the resume. |
| `status` | `enum` | Current workflow state (see Enums below). |
| `comments` | `text` | Optional internal notes provided by the applicant or admin. |
| `created_at` | `timestamp`| Record creation timestamp. |
| `updated_at` | `timestamp`| Last modification timestamp. |

### Enumerated Types

#### `application_status`
The system uses a custom PostgreSQL enum to manage the application workflow:
*   `pending`: The default state upon submission.
*   `reviewed`: The admin has opened and inspected the application.
*   `accepted`: The applicant has been approved for the course.
*   `rejected`: The application has been declined.

---

## TypeScript Definitions

The project uses auto-generated types from the Supabase CLI, located at `src/integrations/supabase/types.ts`. This allows for strict typing when performing CRUD operations.

### Usage Example

To use the applicant type within a React component or service:

```typescript
import { Database } from "@/integrations/supabase/types";

// Extract the Row type for the applicants table
export type Applicant = Database["public"]["Tables"]["applicants"]["Row"];

// Example: Fetching a typed applicant
const fetchApplicant = async (id: string): Promise<Applicant | null> => {
  const { data, error } = await supabase
    .from("applicants")
    .select("*")
    .eq("id", id)
    .single();

  if (error) throw error;
  return data;
};
```

### Insert and Update Types
Supabase provides specific types for inserting (where `id` might be optional) and updating (where all fields are optional).

```typescript
import { TablesInsert, TablesUpdate } from "@/integrations/supabase/types";

// Type for creating a new application
const newApplication: TablesInsert<"applicants"> = {
  full_name: "John Doe",
  email: "john@example.com",
  cv_file_path: "path/to/resume.pdf",
  // status defaults to 'pending' in DB
};
```

---

## Storage Schema

Resumes are stored as binary objects in a dedicated Supabase Storage bucket.

*   **Bucket Name**: `cvs`
*   **File Format**: Restricted to `application/pdf`.
*   **Naming Convention**: Files are typically prefixed with a timestamp (e.g., `1715634000-resume.pdf`) to prevent naming collisions.
*   **Access**: Managed via RLS (Row Level Security) policies, ensuring only authenticated administrators can download files via the `cv_file_path` reference.

## Internal Processing Fields

The following fields are populated asynchronously by the `parse-cv` Edge Function after a user submits their form:
*   `cv_extracted_text`
*   `keyword_match_score`
*   `matched_keywords`

These fields should be treated as **read-only** in the frontend `ApplicantForm` and are only modified by the admin or the automated background worker.

---

## Email Notification Service

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/email-notification-service-271f181d

The Email Notification Service provides automated communication between the recruitment team and applicants. It ensures that candidates are kept informed of their application progress in real-time as administrators update their status within the system.

## Overview
The system integrates with **Resend** via Supabase Edge Functions to dispatch professionally formatted HTML emails. Notifications are triggered automatically when an administrator changes an applicant's status in the **Applicant Detail** view.

### Key Features
*   **Automatic Triggers:** Notifications are sent immediately upon status updates.
*   **Dynamic Templates:** Personalized emails including the applicant's name and their preferred Japanese course.
*   **Visual Branding:** Styled HTML templates with clear calls to action and status-specific messaging.

---

## Supported Status Notifications

The service maps internal application states to specific email templates:

| Status | Email Subject | Purpose |
| :--- | :--- | :--- |
| **Reviewed** | Your Application is Under Review | Informs the candidate that their profile is being actively evaluated. |
| **Accepted** | Congratulations! Your Application Has Been Accepted | A congratulatory message welcoming the student to their selected course. |
| **Rejected** | Update on Your Application | A polite notification informing the candidate they will not be moving forward. |
| **Pending** | Application Status Update | A generic update indicating the application is back in the queue. |

---

## Technical Configuration

The notification service is hosted as a Supabase Edge Function. To ensure emails are delivered successfully, the following configuration is required.

### Prerequisites
1.  A **Resend** account and API Key.
2.  The API Key must be added to your Supabase project secrets:
    ```bash
    supabase secrets set RESEND_API_KEY=re_your_api_key_here
    ```

### Edge Function Interface
The service is located at `/supabase/functions/send-status-notification`. It accepts a `POST` request with the following JSON schema:

```typescript
interface StatusNotificationRequest {
  applicantName: string;    // Full name of the applicant
  applicantEmail: string;   // Recipient address
  newStatus: string;         // 'pending' | 'reviewed' | 'accepted' | 'rejected'
  preferredCourse: string;   // The course the applicant applied for
}
```

### Usage Example (Frontend)
The notification is typically triggered from the `ApplicantDetail` page using the `supabase.functions.invoke` method:

```typescript
const { data, error } = await supabase.functions.invoke("send-status-notification", {
  body: {
    applicantName: "John Doe",
    applicantEmail: "john@example.com",
    newStatus: "accepted",
    preferredCourse: "JLPT N3 Preparation",
  },
});
```

---

## Delivery Behavior & Limitations

*   **Sender Identity:** By default, emails are sent from `Admissions <onboarding@resend.dev>`. In production environments, this should be updated to a verified domain in the Resend dashboard.
*   **Demo Mode:** During the internship/demo phase, the service is configured to route notifications to a hardcoded administrator email (`ashishupadhyay7353@gmail.com`) for testing purposes. To enable direct applicant delivery, update the `to` field in the Edge Function's `resend.emails.send` call.
*   **Error Handling:** If an email fails to send (e.g., due to an invalid API key), the system will still update the applicant's status in the database but will display a warning toast to the administrator: *"Status updated (Email notification failed)"*.

---

## Environment Configuration

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/environment-configuration-dc8ae23a

## Environment Configuration

To run the Japanese ATS Resume Analyzer, you must configure both the frontend environment variables and the Supabase Edge Function secrets. This project relies on **Supabase** for database and storage, and **Resend** for automated email notifications.

### 1. Frontend Environment Variables

Create a `.env` file in the root of your project directory. These variables are required by Vite to connect the React application to your Supabase instance.

```env
# Supabase Configuration
VITE_SUPABASE_URL=https://your-project-id.supabase.co
VITE_SUPABASE_ANON_KEY=your-public-anon-key
```

*   **VITE_SUPABASE_URL**: Found in your Supabase Project Settings under **API**.
*   **VITE_SUPABASE_ANON_KEY**: The public "anon" key found in your Supabase Project Settings under **API**.

### 2. Supabase Edge Functions Secrets

The system uses Edge Functions for server-side logic (CV parsing and email notifications). These variables must be set within the Supabase CLI or Dashboard to be accessible at runtime.

#### Resend Integration
The `send-status-notification` function requires a Resend API key to transmit emails to applicants.

```bash
# Set secret using Supabase CLI
supabase secrets set RESEND_API_KEY=re_your_api_key
```

*   **RESEND_API_KEY**: Obtain this from your [Resend Dashboard](https://resend.com/dashboard).

#### Internal System Keys
The `parse-cv` function requires administrative access to update applicant records after processing. While Supabase provides these automatically in the production environment, ensure your project environment has access to:
*   `SUPABASE_URL`
*   `SUPABASE_SERVICE_ROLE_KEY` (Required for bypassing Row Level Security during background processing)

### 3. Supabase Storage Setup

The application expects a specific storage bucket to handle resume uploads. 

1.  Navigate to **Storage** in your Supabase Dashboard.
2.  Create a new bucket named `cvs`.
3.  Set the bucket privacy to **Public** (or configure appropriate [Storage Policies](https://supabase.com/docs/guides/storage/security/access-control) to allow the `authenticated` role to upload and the `service_role` to download).

### 4. Database Schema

Ensure your Supabase database contains the `applicants` table. The application expects the following structure (automatically generated if using the provided SQL migrations):

| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | uuid | Unique identifier (Primary Key) |
| `full_name` | text | Applicant's name |
| `email` | text | Applicant's email address |
| `cv_file_path` | text | Reference to the file in the `cvs` bucket |
| `status` | enum | `pending`, `reviewed`, `accepted`, `rejected` |
| `keyword_match_score` | int4 | Calculated ATS score (0-100) |
| `matched_keywords` | text[] | Array of identified skills/keywords |

### 5. Local Development (Optional)

If you are running Supabase Edge Functions locally for testing, create a `.env` file inside the `supabase/functions/` directory or pass them via the CLI:

```bash
supabase start
supabase functions serve --no-verify-jwt --env-file ./supabase/.env.local
```

---

## File Storage & Security

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/file-storage-security-7302f527

## Storage Architecture

The Japanese ATS utilizes **Supabase Storage** to manage resume uploads, ensuring that candidate documents are stored in a scalable, cloud-native environment rather than locally on the web server.

### The `cvs` Bucket
All uploaded resumes are stored in a dedicated Supabase Storage bucket named `cvs`. To prevent filename collisions when multiple candidates upload files with identical names (e.g., `resume.pdf`), the system implements a unique naming convention during the upload process:

```typescript
// Example of the unique file path generation
const fileName = `${Date.now()}-${cvFile.name}`;
```

### File Constraints & Validation
To maintain system performance and security, the application enforces the following restrictions on the client side before any data is sent to storage:

| Constraint | Value | Description |
| :--- | :--- | :--- |
| **File Type** | `.pdf` | Only PDF documents are accepted to ensure compatibility with the background parser. |
| **File Size** | 5MB | Files exceeding this limit are rejected to minimize storage costs and latency. |
| **Storage Path** | `cvs/{timestamp}-{filename}` | Standardized pathing for easy retrieval and auditing. |

---

## Security Framework

Security is implemented through a multi-layered approach involving **Supabase Auth**, **Row Level Security (RLS)**, and React-based **Protected Routes**.

### Authentication & Access Control
The system maintains a strict boundary between public applicants and administrative staff:

*   **Public Access:** Candidates can submit data and upload files to the `cvs` bucket but cannot view, edit, or delete existing records.
*   **Admin Access:** Requires authentication via Supabase Auth. Only logged-in administrators can access the Dashboard or view detailed applicant profiles.

### Row Level Security (RLS)
The database schema for the `applicants` table is designed to support RLS policies. This ensures that even if a malicious actor attempts to bypass the UI, the database itself will reject unauthorized requests.

**Recommended RLS Policies:**
*   **Insert:** Enable for all users (to allow application submissions).
*   **Select/Update/Delete:** Restricted to authenticated admin users only.

### Secure File Retrieval
Resumes are not stored in a public directory. To view or download a resume, the Admin Dashboard generates a secure request to the Supabase storage API. 

```typescript
// Internal logic for secure CV download in AdminDetail.tsx
const { data, error } = await supabase.storage
  .from("cvs")
  .download(applicant.cv_file_path);
```

### Edge Function Security
The system utilizes Supabase Edge Functions for sensitive tasks such as **CV Parsing** and **Email Notifications**.
*   **Service Role Access:** Functions use the `SUPABASE_SERVICE_ROLE_KEY` to interact with the database, allowing them to perform administrative tasks (like updating match scores) without exposing high-level credentials to the frontend.
*   **CORS Management:** Edge functions include strict Cross-Origin Resource Sharing (CORS) headers to ensure they only respond to requests from the authorized application domain.

---

## Introduction

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/introduction-200d6ff8

## Overview

The **Japanese ATS Resume Analyzer** is a specialized Applicant Tracking System designed to streamline the recruitment and admission process for Japanese language programs and professional roles. Developed as part of an academic internship project, the system bridges the gap between manual application review and automated candidate shortlisting through intelligent resume parsing and keyword matching.

The platform provides a dual-interface experience: an intuitive submission portal for applicants and a robust management dashboard for administrators to track, score, and notify candidates.

## Core Value Proposition

In traditional recruitment, manually filtering resumes for specific technical skills or language proficiencies (such as JLPT levels) is time-consuming. This system automates that process by:

*   **Automated Resume Parsing:** Extracting text directly from PDF uploads using cloud-based functions.
*   **Keyword-Based Shortlisting:** Comparing extracted resume text against a predefined set of industry-standard keywords (e.g., "JLPT N2," "TypeScript," "React").
*   **Status Management:** Providing a unified workflow to move candidates from "Pending" to "Accepted" or "Rejected" with automated email feedback.

## Key Features

### For Applicants
*   **Streamlined Application:** A validated form to capture personal details, educational background, and experience.
*   **Secure Resume Upload:** Integrated PDF upload functionality.
*   **Instant Feedback:** Visual confirmation upon successful submission.

### For Administrators
*   **Candidate Dashboard:** A high-level overview of all applicants with sorting and filtering capabilities.
*   **Intelligence Scoring:** View "Keyword Match Scores" to quickly identify high-potential candidates.
*   **Document Management:** One-click download of original PDF resumes.
*   **Automated Notifications:** Change application statuses and trigger automated email notifications via the Resend API integration.
*   **Data Portability:** Export candidate lists to CSV for external reporting and analysis.

## System Workflow

The system operates on a modern serverless architecture. When an applicant submits their CV, the following sequence occurs:

1.  **Storage:** The PDF is stored in a Supabase Storage bucket.
2.  **Trigger:** An Edge Function (`parse-cv`) is invoked.
3.  **Extraction:** The system extracts raw text from the PDF.
4.  **Analysis:** The text is scanned for relevant keywords, and a matching score is calculated.
5.  **Persistence:** The score and matched keywords are saved back to the database for the administrator to review.

### Application Data Model

Administrators and developers can interact with the following core data structure within the `applicants` table:

```typescript
interface Applicant {
  id: string;
  full_name: string;
  email: string;
  highest_degree: string;
  years_of_experience: number;
  preferred_course: string; // e.g., "JLPT N2 Preparation"
  status: "pending" | "reviewed" | "accepted" | "rejected";
  keyword_match_score: number | null; // Calculated 0-100
  matched_keywords: string[] | null;
  cv_file_path: string;
}
```

## Technology Stack

The application is built with a focus on performance and type safety:

*   **Frontend:** React with TypeScript, powered by Vite.
*   **Styling:** Tailwind CSS with shadcn-ui components for a professional, accessible interface.
*   **Backend/Database:** Supabase (PostgreSQL, Auth, and Storage).
*   **Automated Logic:** Supabase Edge Functions (Deno).
*   **Notifications:** Resend API for transactional email.

---

## Keyword Matching Algorithm

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/keyword-matching-algorithm-395dbd2f

## Keyword Matching & Scoring

The Japanese ATS includes an automated resume analyzer designed to help administrators quickly identify qualified candidates. When an applicant uploads a PDF resume, the system extracts the text and compares it against a standardized dictionary of professional keywords.

### The Keyword Dictionary

The algorithm scans for a wide range of professional competencies, specifically tailored for technical and language-oriented roles. The pre-defined dictionary includes:

*   **Japanese Proficiency:** JLPT levels (N1, N2, N3, N4, N5) and general language skills.
*   **Programming Languages:** Java, JavaScript, TypeScript, Python, C++, Ruby, etc.
*   **Web & Cloud Technologies:** React, Node.js, AWS, Azure, Docker, and CI/CD.
*   **Databases:** SQL, PostgreSQL, MongoDB, and others.
*   **Professional Experience:** Titles like "Senior," "Lead," "Architect," and "Manager."
*   **Education:** Verification of degrees (Bachelor, Master, PhD).

### Scoring Mechanism

The **Keyword Match Score** provides a quantitative measure of how well a resume aligns with the system's target criteria. 

*   **Match Increment:** Each unique keyword found in the resume adds **10%** to the total score.
*   **Maximum Score:** The score is capped at **100%**.
*   **Precision Matching:** The algorithm uses word-boundary detection (Regex) to ensure accuracy. For example, it distinguishes "Java" from "JavaScript" and correctly identifies terms with symbols like "C++" or "C#".

### Analysis Process

1.  **Text Extraction:** Upon submission, a background Edge Function processes the uploaded PDF using `pdfjs-dist` to convert document layouts into searchable text.
2.  **Normalization:** The extracted text and keywords are normalized to lowercase to ensure the matching is case-insensitive.
3.  **Keyword Identification:** The system runs a comparison between the resume text and the global dictionary (plus any custom keywords provided).
4.  **Database Update:** The resulting score and a list of specific "Matched Keywords" are stored alongside the applicant's profile.

### Administrator View

Administrators can view these metrics directly within the **Admin Dashboard** and **Applicant Detail** pages:

*   **Match Score Badge:** A visual percentage indicator that helps in rapid shortlisting.
*   **Matched Keywords List:** A set of tags showing exactly which relevant terms were found in the candidate's CV.
*   **Extracted Text:** For transparency, administrators can view the raw text extracted from the PDF to verify the context of specific keywords.

```typescript
// Example of how the score is calculated internally:
const score = Math.min(100, matchedKeywords.length * 10);
```

### Limitations
*   **File Format:** Currently, the keyword matching algorithm only supports **PDF** files.
*   **Image-based PDFs:** Resumes that are saved as images (scanned documents) without an OCR layer cannot be read by the current extractor. Candidates are encouraged to upload text-based PDFs for the best results.

---

## Quick Start

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/quick-start-b78c08b5

## Getting Started

Follow these steps to set up the Japanese ATS project locally on your machine. This application requires a Supabase instance to handle database storage, authentication, and resume processing.

### Prerequisites

Before you begin, ensure you have the following installed:
- **Node.js** (v18.0 or higher)
- **npm** or **bun** (package manager)
- A **Supabase** account (for backend services)
- A **Resend** API key (optional, for email notifications)

### 1. Clone the Repository

Start by cloning the project to your local environment:

```bash
git clone https://github.com/ashish-upadhyay2004/JapaneseATS-Resume-Analyzer.git
cd JapaneseATS-Resume-Analyzer
```

### 2. Install Dependencies

Install the required project dependencies using your preferred package manager:

```bash
# Using npm
npm install

# Using bun
bun install
```

### 3. Environment Configuration

Create a `.env` file in the root directory and add your Supabase credentials. These can be found in your Supabase Project Settings under **API**.

```env
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
```

### 4. Database and Storage Setup

To ensure the application functions correctly, you must set up your Supabase project with the following:

1.  **Tables**: Create an `applicants` table as defined in `src/integrations/supabase/types.ts`.
2.  **Storage**: Create a public bucket named `cvs` to store uploaded PDF resumes.
3.  **Edge Functions**: Deploy the functions located in the `/supabase/functions` directory:
    - `parse-cv`: Handles PDF text extraction and keyword matching.
    - `send-status-notification`: Manages email updates via Resend.

### 5. Launch the Development Server

Start the Vite development server to view the application:

```bash
npm run dev
```

Once the server is running, the application is accessible at `http://localhost:5173`.

---

## User Workflows

### Applicant View
- **URL**: `/`
- **Action**: Fill out the application form and upload a PDF resume. 
- **Validation**: The system checks for PDF format and file size (max 5MB). Upon submission, the background `parse-cv` function will automatically analyze the resume for keywords.

### Admin Dashboard
- **URL**: `/admin/login`
- **Action**: Log in using your Supabase Auth credentials.
- **Dashboard**: View the list of applicants, their automated "Match Scores," and update application statuses (Pending, Reviewed, Accepted, Rejected). Updating a status triggers an automated email notification to the candidate.

---

## State & Query Management

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/state-query-management-2a20314c

## State & Query Management

The Japanese ATS leverages a modern state management architecture to ensure data integrity, responsive UI updates, and efficient server synchronization. The system separates concerns between **Server State** (managed by TanStack Query) and **Form State** (managed by React Hook Form).

### Server State with TanStack Query

The application utilizes **TanStack Query (React Query)** to handle asynchronous data fetching, caching, and synchronization with the Supabase backend. This approach reduces boilerplate code and provides built-in support for loading states and error handling.

#### Global Configuration
The `QueryClient` is initialized at the root level in `App.tsx`, providing a centralized cache for all application data.

```tsx
// src/App.tsx
const queryClient = new QueryClient();

const App = () => (
  <QueryClientProvider client={queryClient}>
    {/* Application Routes */}
  </QueryClientProvider>
);
```

#### Usage in Admin Modules
Admin pages, such as the Dashboard and Applicant Details, interact with the Supabase client to retrieve records. While some components utilize standard React lifecycle hooks, the architecture is designed to support query-based fetching for optimized performance and automatic background refetching.

### Form Management & Client-Side Validation

For complex data entry, such as the applicant submission form, the project uses **React Hook Form** paired with **Zod** for schema-based validation. This ensures that only valid data is sent to the database.

#### Applicant Form Schema
The validation logic is centralized in a Zod schema, defining strict rules for user input, including file size constraints for resume uploads.

| Field | Validation Rule |
| :--- | :--- |
| `fullName` | String, 2-100 characters |
| `email` | Valid email format, max 255 characters |
| `yearsOfExperience` | Number, range 0 to 50 |
| `highestDegree` | Required selection |
| `preferredCourse` | Required selection |
| `cvFile` | PDF format only, maximum 5MB |

#### Implementation Example
The `Index.tsx` page implements the application form using the `useForm` hook. It handles both the structured text data and the binary file upload to Supabase Storage.

```tsx
const formSchema = z.object({
  fullName: z.string().min(2, "Name must be at least 2 characters"),
  email: z.string().email("Invalid email address"),
  // ... other fields
});

const form = useForm<z.infer<typeof formSchema>>({
  resolver: zodResolver(formSchema),
});

const onSubmit = async (data: FormData) => {
  // Logic for CV upload and Database insertion
};
```

### Persistence and Type Safety

The application's state is strictly typed using generated Supabase types, ensuring that the frontend state always aligns with the database schema.

*   **Type Definitions:** Located in `src/integrations/supabase/types.ts`.
*   **Database Interactions:** The `supabase` client is used directly within hooks and components to perform CRUD operations, ensuring that the application remains lightweight without the need for a heavy global state library like Redux.

### User Feedback (Toasts)
State transitions (such as "Submitting", "Success", or "Error") are communicated to the user through the `sonner` and `shadcn-ui/toaster` libraries. These are triggered during the mutation lifecycle to provide real-time feedback.

```tsx
try {
  // perform action
  toast.success("Application submitted successfully!");
} catch (error) {
  toast.error("Failed to submit application");
}
```

---

## Supabase Edge Functions

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/supabase-edge-functions-6fa6881b

Supabase Edge Functions handle the application's background processing tasks, such as parsing PDF documents and sending automated email notifications. These functions are written in TypeScript and run on Deno, ensuring high performance and security without the need for a dedicated backend server.

## Overview
The Japanese ATS utilizes two primary edge functions to automate the recruitment workflow:
1.  **`parse-cv`**: Automatically extracts text from resumes and calculates a keyword match score.
2.  **`send-status-notification`**: Sends branded email updates to applicants when their application status changes.

---

## CV Parsing and Analysis (`parse-cv`)
This function is triggered immediately after an applicant submits their form. It processes the uploaded PDF in the background to provide administrators with instant insights into the candidate's qualifications.

### Trigger Mechanism
The function is invoked from the `Apply` page after a successful file upload to Supabase Storage and a database record creation.

### Usage
```typescript
const { data, error } = await supabase.functions.invoke("parse-cv", {
  body: {
    applicantId: "uuid-of-applicant",
    cvFilePath: "path/to/resume.pdf",
    customKeywords: ["N1", "React", "Management"] // Optional
  },
});
```

### Request Payload
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `applicantId` | `string` | Yes | The unique ID of the applicant in the database. |
| `cvFilePath` | `string` | Yes | The path to the file in the `cvs` storage bucket. |
| `customKeywords` | `string[]` | No | Additional keywords to search for in the resume. |

### Functionality
- **Text Extraction**: Uses `pdfjs-dist` to read text content from PDF files.
- **Keyword Matching**: Scans extracted text against a predefined list of technical skills (languages, frameworks, databases) and Japanese language proficiency levels (JLPT N1–N5).
- **Scoring**: Calculates a `keyword_match_score` based on the density of relevant keywords.
- **Database Update**: Automatically populates the `cv_extracted_text`, `matched_keywords`, and `keyword_match_score` columns in the `applicants` table.

---

## Email Notifications (`send-status-notification`)
This function integrates with the **Resend** API to manage communication between the admissions team and the applicants.

### Trigger Mechanism
The function is invoked by the Admin Dashboard whenever an administrator updates an applicant's status (e.g., from "Pending" to "Accepted").

### Usage
```typescript
const { data, error } = await supabase.functions.invoke("send-status-notification", {
  body: {
    applicantName: "John Doe",
    applicantEmail: "john@example.com",
    newStatus: "accepted",
    preferredCourse: "JLPT N2 Preparation"
  },
});
```

### Request Payload
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `applicantName` | `string` | Yes | The full name of the candidate. |
| `applicantEmail` | `string` | Yes | The recipient's email address. |
| `newStatus` | `string` | Yes | Must be `pending`, `reviewed`, `accepted`, or `rejected`. |
| `preferredCourse` | `string` | Yes | The course the candidate applied for. |

### Email Templates
The function automatically selects a relevant HTML template based on the `newStatus`:
- **Reviewed**: Notifies the candidate that their application is under active consideration.
- **Accepted**: Sends a congratulatory message with green-themed branding.
- **Rejected**: Sends a professional and encouraging rejection notice.

---

## Configuration & Environment Variables
To run these functions, the following Supabase Secrets must be configured:

| Secret Name | Description |
| :--- | :--- |
| `SUPABASE_URL` | The project URL for storage and database access. |
| `SUPABASE_SERVICE_ROLE_KEY` | Needed for the `parse-cv` function to bypass RLS and update applicant records. |
| `RESEND_API_KEY` | Your API key from [Resend](https://resend.com) for sending emails. |

### Local Development
To test functions locally, use the Supabase CLI:
```bash
supabase functions serve --no-verify-jwt
```
*Note: The `--no-verify-jwt` flag is recommended for local development if you are invoking functions directly from the frontend without Auth headers.*

---

## UI System & Shadcn/UI

**Project:** japaneseats-resume-analyzer
**URL:** https://japaneseats-resume-analyzer.superdocs.cloud/ui-system-shadcn-ui-2fa3e30e

## Overview

The Japanese ATS (Applicant Tracking System) utilizes a modern UI system built on **Radix UI** primitives and **Tailwind CSS**, orchestrated via **shadcn/ui**. This architecture ensures a highly accessible, accessible, and performant user interface that maintains a professional aesthetic suitable for recruitment software.

The system emphasizes high readability, clear status indicators, and smooth transitions to guide users through the application and administrative workflows.

## Design Tokens & Theme

The UI is defined by a set of CSS variables located in `src/index.css`. These tokens control the visual identity of the application.

### Color Palette
The system uses a sophisticated color palette designed for clarity and professional data presentation:

*   **Primary (`--primary`):** A professional blue (#3b82f6) used for main actions and branding.
*   **Accent (`--accent`):** A teal/mint color used for highlights and specific call-to-actions.
*   **Status Colors:** Custom tokens are defined for application states:
    *   `--success`: Green (Accepted)
    *   `--warning`: Amber (Pending/Action Required)
    *   `--info`: Blue/Cyan (Reviewed)
    *   `--destructive`: Red (Rejected/Errors)

### Typography
The application uses a dual-font strategy:
*   **Headings:** `Plus Jakarta Sans` for a modern, high-contrast look in titles and section headers.
*   **Body:** `Inter` for maximum legibility in forms, tables, and applicant data.

### Custom Gradients & Shadows
To enhance the visual hierarchy, several custom utility classes are available:
*   `.gradient-primary`: A 135-degree blue-to-cyan gradient.
*   `.gradient-hero`: A high-impact gradient used for landing sections.
*   `.shadow-primary`: A soft, colored glow effect for primary buttons and cards.

## Component Architecture

The project follows the shadcn/ui "copy-and-paste" philosophy. Components are located in `src/components/ui/` and are built as thin wrappers around Radix UI primitives.

### Common UI Components
| Component | Usage |
| :--- | :--- |
| `Button` | Standardized buttons with variants like `default`, `outline`, and `ghost`. |
| `Badge` | Used for status indicators (e.g., "Pending", "Accepted"). |
| `Toaster` | Accessible toast notifications for form submissions and admin actions. |
| `Select` | Styled dropdowns for degree selection and course preferences. |
| `Form` | Accessible form fields with built-in validation messages (via React Hook Form + Zod). |

## Custom Components

### NavLink
The `NavLink` component (located in `src/components/NavLink.tsx`) is a specialized wrapper around `react-router-dom`’s `NavLink`. It simplifies the application of active and pending styles.

**Usage:**
```tsx
import { NavLink } from "@/components/NavLink";

<NavLink 
  to="/admin/dashboard" 
  className="text-gray-500" 
  activeClassName="text-primary font-bold"
>
  Dashboard
</NavLink>
```

## Motion & Transitions

The system includes pre-configured animations to improve the perceived speed and user experience of the interface. These are available as Tailwind utility classes:

*   `animate-fade-in`: Gradually fades an element in.
*   `animate-slide-up`: Fades an element in while sliding it up 20px (ideal for form headers).
*   `animate-scale-in`: A subtle "pop" effect used for success modals and cards.

**Example Usage:**
```tsx
<div className="card-elevated animate-scale-in">
  {/* Content that pops in when rendered */}
</div>
```

## Dark Mode Support

The UI system is fully compatible with dark mode. Theme variables are re-defined in the `.dark` class block within `src/index.css`, adjusting background contrasts and surface colors to ensure the ATS remains readable in low-light environments.

To toggle or force dark mode, ensure the `dark` class is applied to the `html` or `body` element.

## Utility Functions

The project uses a standard `cn` utility (located in `src/lib/utils.ts`) to merge Tailwind classes efficiently, handling conditional logic and preventing class conflicts.

```tsx
import { cn } from "@/lib/utils";

const MyComponent = ({ className, isActive }) => (
  <div className={cn("base-styles", isActive && "active-styles", className)}>
    Content
  </div>
);
```