Upload 60 files

alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration with an async dbapi.

alembic/env.py

@@ -0,0 +1,95 @@
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+from app.core.config import settings
+from app.core.db import Base
+# Import all models so Alembic can discover them
+import app.models.resume
+import app.models.analysis
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

alembic/versions/8606f9c05795_initial_tables.py

@@ -0,0 +1,59 @@
+"""Initial tables
+
+Revision ID: 8606f9c05795
+Revises: 
+Create Date: 2026-07-12 19:11:23.136578
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '8606f9c05795'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('resumes',
+    sa.Column('id', sa.String(), nullable=False),
+    sa.Column('session_id', sa.String(), nullable=False),
+    sa.Column('file_name', sa.String(), nullable=False),
+    sa.Column('file_path', sa.String(), nullable=False),
+    sa.Column('extracted_text', sa.Text(), nullable=False),
+    sa.Column('pages', sa.Integer(), nullable=False),
+    sa.Column('uploaded_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_resumes_session_id'), 'resumes', ['session_id'], unique=False)
+    op.create_table('analyses',
+    sa.Column('id', sa.String(), nullable=False),
+    sa.Column('resume_id', sa.String(), nullable=False),
+    sa.Column('session_id', sa.String(), nullable=False),
+    sa.Column('job_description', sa.Text(), nullable=False),
+    sa.Column('target_role', sa.String(), nullable=False),
+    sa.Column('result', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['resume_id'], ['resumes.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_analyses_resume_id'), 'analyses', ['resume_id'], unique=False)
+    op.create_index(op.f('ix_analyses_session_id'), 'analyses', ['session_id'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_analyses_session_id'), table_name='analyses')
+    op.drop_index(op.f('ix_analyses_resume_id'), table_name='analyses')
+    op.drop_table('analyses')
+    op.drop_index(op.f('ix_resumes_session_id'), table_name='resumes')
+    op.drop_table('resumes')
+    # ### end Alembic commands ###

app/api/deps.py

@@ -0,0 +1,13 @@
+import uuid
+from typing import Annotated
+
+from fastapi import Header
+
+
+async def get_session_id(x_session_id: Annotated[str | None, Header()] = None) -> str:
+    """
+    Return the session ID from the X-Session-Id header.
+    If the header is absent, generate a fresh UUID so every resource
+    is still scoped to *some* session.
+    """
+    return x_session_id or str(uuid.uuid4())

app/api/routes/analysis.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.api.deps import get_session_id
+from app.core.logging import get_logger
+from app.models.analysis import AnalysisRecord
+from app.models.resume import ResumeRecord
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.db import get_db
+from app.schemas.analysis import (
+    AnalysisDetail,
+    AnalyzeRequest,
+    AnalyzeResponse,
+    BulletRewrite,
+    ComponentBreakdown,
+    Recommendation,
+    ScoreWeights,
+    SectionNote,
+)
+from app.services.ats_scoring import ATSResult, run_ats_scoring
+
+logger = get_logger(__name__)
+router = APIRouter()
+
+
+# ── POST /api/analyze ─────────────────────────────────────────────────────
+
+@router.post(
+    "/analyze",
+    response_model=AnalyzeResponse,
+    tags=["analysis"],
+    summary="Analyse resume against a job description",
+)
+async def analyze(
+    body: AnalyzeRequest,
+    session_id: Annotated[str, Depends(get_session_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> AnalyzeResponse:
+    """
+    Run the full ATS-style analysis pipeline:
+      1. Fetch extracted resume text.
+      2. Parse sections.
+      3. Extract and compare keywords.
+      4. Compute semantic similarity.
+      5. Compute weighted ATS score.
+      6. Return structured result.
+
+    Bullet rewrites are empty in Phase 2 — LLM populates them in Phase 4.
+    """
+    # ── Fetch resume ──────────────────────────────────────────────────────
+    record = await db.get(ResumeRecord, body.resume_id)
+    if record is None or record.session_id != session_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Resume not found in this session.",
+        )
+
+    logger.info(
+        "analyze: resume_id=%s session=%s jd_chars=%d role=%r",
+        body.resume_id, session_id, len(body.job_description), body.target_role,
+    )
+
+    # ── Run scoring pipeline ──────────────────────────────────────────────
+    try:
+        result: ATSResult = run_ats_scoring(
+            resume_text=record.extracted_text,
+            jd_text=body.job_description,
+            target_role=body.target_role,
+        )
+    except Exception as exc:
+        logger.exception("Scoring pipeline failed: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Analysis failed — please retry.",
+        ) from exc
+
+    # ── Build response ────────────────────────────────────────────────────
+    response = _build_response(result, record.file_name)
+
+    # ── LLM Bullet Rewrites (Phase 4) ─────────────────────────────────────
+    import asyncio
+    from app.services.llm_service import rewrite_weak_bullets
+    
+    try:
+        # Run sync Gemini call in threadpool to avoid blocking ASGI loop
+        rewrites_raw = await asyncio.to_thread(
+            rewrite_weak_bullets,
+            bullets=result.parsed.experience_bullets,
+            job_description=body.job_description,
+            target_role=body.target_role,
+            max_rewrites=3
+        )
+        # Map to Pydantic objects
+        response.bullet_rewrites = [BulletRewrite(**rw) for rw in rewrites_raw]
+    except Exception as exc:
+        logger.warning("LLM rewrite failed: %s", exc)
+        # Non-fatal, just leave rewrites empty
+        pass
+
+    # ── Persist ───────────────────────────────────────────────────────────
+    ar = AnalysisRecord(
+        resume_id=body.resume_id,
+        session_id=session_id,
+        job_description=body.job_description,
+        target_role=body.target_role,
+        result=response.model_dump(),
+    )
+    db.add(ar)
+    await db.commit()
+    await db.refresh(ar)
+    response.analysis_id = ar.id
+
+    logger.info(
+        "analyze: analysis_id=%s overall=%d latency_ms=%d",
+        ar.id, result.overall_score, result.latency_ms,
+    )
+
+    return response
+
+
+# ── GET /api/analysis/{analysis_id} ──────────────────────────────────────
+
+@router.get(
+    "/analysis/{analysis_id}",
+    response_model=AnalysisDetail,
+    tags=["analysis"],
+    summary="Get past analysis result",
+)
+async def get_analysis(
+    analysis_id: str,
+    session_id: Annotated[str, Depends(get_session_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> AnalysisDetail:
+    """Fetch an analysis result generated in this session."""
+    ar = await db.get(AnalysisRecord, analysis_id)
+    if ar is None or ar.session_id != session_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Analysis not found in this session.",
+        )
+    return AnalysisDetail(
+        analysis_id=ar.id,
+        resume_id=ar.resume_id,
+        created_at=ar.created_at,
+        result=AnalyzeResponse(**ar.result),
+    )
+
+
+# ── Private helpers ───────────────────────────────────────────────────────
+
+def _role_fit(score: int) -> tuple[str, str]:
+    if score >= 80:
+        return (
+            "Strong fit",
+            "Resume aligns well with the JD across skills and experience. "
+            "Fix the missing keywords and quantify a few bullets to push into shortlist range.",
+        )
+    if score >= 65:
+        return (
+            "Moderate fit",
+            "Core skills overlap but presentation and specificity are weak. "
+            "Prioritise the top-3 missing keywords and add measurable outcomes.",
+        )
+    return (
+        "Needs work",
+        "Significant gaps in skills or presentation. "
+        "Address missing keywords first, then rewrite bullets around measurable outcomes.",
+    )
+
+
+def _recommendations(result: ATSResult, file_name: str) -> list[Recommendation]:
+    recs: list[Recommendation] = []
+    comp = result.components
+    kw   = result.keywords
+
+    if kw.missing:
+        top3 = ", ".join(kw.missing[:3])
+        recs.append(Recommendation(
+            priority="high", category="keywords",
+            message=f"Add missing keywords: {top3}. These appear in the JD but not in your resume.",
+        ))
+
+    if comp.experience_alignment < 60:
+        recs.append(Recommendation(
+            priority="high", category="experience",
+            message="Quantify at least 5 bullets with numbers, percentages, or impact metrics.",
+        ))
+
+    if comp.semantic_similarity < 55:
+        recs.append(Recommendation(
+            priority="high", category="alignment",
+            message="Rephrase your summary and experience to mirror the language and priorities in the JD.",
+        ))
+
+    if not result.parsed.summary:
+        recs.append(Recommendation(
+            priority="medium", category="structure",
+            message="Add a 2-line summary at the top tailored to this specific role.",
+        ))
+
+    if not result.parsed.certifications_raw:
+        recs.append(Recommendation(
+            priority="low", category="certifications",
+            message="Even one relevant certification improves ATS signal and fills a structural gap.",
+        ))
+
+    if kw.weak:
+        recs.append(Recommendation(
+            priority="medium", category="keywords",
+            message=f"Strengthen underused keywords: {', '.join(kw.weak[:3])}. Mention them in context.",
+        ))
+
+    return recs[:6]   # cap at 6 recommendations
+
+
+def _build_response(result: ATSResult, file_name: str) -> AnalyzeResponse:
+    verdict, summary = _role_fit(result.overall_score)
+    comp = result.components
+
+    return AnalyzeResponse(
+        analysis_id="",          # filled in after persist
+        overall_score=result.overall_score,
+        weights=ScoreWeights(),
+        components=ComponentBreakdown(
+            keyword_coverage=comp.keyword_coverage,
+            semantic_similarity=comp.semantic_similarity,
+            skills_overlap=comp.skills_overlap,
+            experience_alignment=comp.experience_alignment,
+            resume_quality=comp.resume_quality,
+        ),
+        matched_keywords=result.keywords.matched,
+        missing_keywords=result.keywords.missing,
+        weak_keywords=result.keywords.weak,
+        section_notes=[
+            SectionNote(
+                section=sn.section,
+                status=sn.status,
+                note=sn.note,
+                score=sn.score,
+            )
+            for sn in result.section_notes
+        ],
+        recommendations=_recommendations(result, file_name),
+        bullet_rewrites=[],   # Phase 4 (LLM)
+        role_fit_verdict=verdict,
+        role_fit_summary=summary,
+        parsed_sections=result.parsed.to_dict(),
+        latency_ms=result.latency_ms,
+    )

app/api/routes/health.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class HealthResponse(BaseModel):
+    status: str
+
+
+@router.get("/health", response_model=HealthResponse, tags=["meta"])
+async def health() -> HealthResponse:
+    """Basic liveness probe."""
+    return HealthResponse(status="ok")

app/api/routes/resume.py

@@ -0,0 +1,135 @@
+import time
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
+
+from app.api.deps import get_session_id
+from app.core.config import settings
+from app.core.logging import get_logger
+from app.models.resume import ResumeRecord
+from app.schemas.resume import ResumeDetail, ResumeUploadResponse
+from app.services.pdf_extractor import ExtractionError, extract_text
+
+logger = get_logger(__name__)
+router = APIRouter()
+
+_ALLOWED_CONTENT_TYPES = {"application/pdf"}
+
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.db import get_db
+
+@router.post(
+    "/resumes/upload",
+    response_model=ResumeUploadResponse,
+    status_code=status.HTTP_201_CREATED,
+    tags=["resumes"],
+    summary="Upload a resume PDF",
+)
+async def upload_resume(
+    file: UploadFile,
+    session_id: Annotated[str, Depends(get_session_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> ResumeUploadResponse:
+    """
+    Accept a PDF resume, extract its text, persist the record, and return
+    an ID for subsequent analysis requests.
+
+    Error codes
+    -----------
+    400 : wrong file type or file too large
+    422 : PDF is unreadable or appears to be scanned / image-only
+    """
+    t0 = time.perf_counter()
+
+    # ── 1. Validate content type ──────────────────────────────────────────
+    if file.content_type not in _ALLOWED_CONTENT_TYPES:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Please upload a PDF resume.",
+        )
+
+    # ── 2. Read and validate size ─────────────────────────────────────────
+    data = await file.read()
+    if len(data) > settings.max_upload_bytes:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Max size is {settings.max_upload_mb} MB.",
+        )
+
+    # ── 3. Persist to disk under session-scoped directory ─────────────────
+    session_dir: Path = settings.upload_dir / session_id
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    safe_name = Path(file.filename or "resume.pdf").name  # strip path traversal
+    dest = session_dir / safe_name
+    dest.write_bytes(data)
+    logger.info("Saved %s (%d bytes) for session %s", safe_name, len(data), session_id)
+
+    # ── 4. Extract text ───────────────────────────────────────────────────
+    try:
+        extracted_text, pages = extract_text(dest)
+    except ExtractionError as exc:
+        # Remove the file so the client can retry with a better PDF
+        dest.unlink(missing_ok=True)
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    # ── 5. Store record ───────────────────────────────────────────────────
+    record = ResumeRecord(
+        session_id=session_id,
+        file_name=safe_name,
+        file_path=str(dest),
+        extracted_text=extracted_text,
+        pages=pages,
+    )
+    db.add(record)
+    await db.commit()
+    await db.refresh(record)
+
+    elapsed_ms = round((time.perf_counter() - t0) * 1000)
+    logger.info(
+        "upload_resume: resume_id=%s pages=%d chars=%d elapsed_ms=%d",
+        record.id,
+        pages,
+        len(extracted_text),
+        elapsed_ms,
+    )
+
+    return ResumeUploadResponse(
+        resume_id=record.id,
+        file_name=safe_name,
+        pages_estimate=pages,
+        extraction_status="success",
+    )
+
+
+@router.get(
+    "/resumes/{resume_id}",
+    response_model=ResumeDetail,
+    tags=["resumes"],
+    summary="Get resume metadata",
+)
+async def get_resume(
+    resume_id: str,
+    session_id: Annotated[str, Depends(get_session_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> ResumeDetail:
+    """Return metadata for a previously uploaded resume (session-scoped)."""
+    record = await db.get(ResumeRecord, resume_id)
+    if record is None or record.session_id != session_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Resume not found in this session.",
+        )
+    return ResumeDetail(
+        resume_id=record.id,
+        file_name=record.file_name,
+        pages=record.pages,
+        extraction_status="success",
+        uploaded_at=record.uploaded_at,
+        char_count=len(record.extracted_text),
+    )

app/core/config.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Upload limits
+    max_upload_mb: int = 5
+
+    # Where uploaded files land on disk
+    upload_dir: Path = Path("./uploads")
+
+    # LLM (Phase 4)
+    gemini_api_key: str = ""
+
+    # Database (Phase 2+)
+    database_url: str = "sqlite+aiosqlite:///./resume.db"
+
+    @property
+    def max_upload_bytes(self) -> int:
+        return self.max_upload_mb * 1024 * 1024
+
+
+settings = Settings()
+
+# Make sure the upload directory exists at startup
+settings.upload_dir.mkdir(parents=True, exist_ok=True)

app/core/db.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import declarative_base
+
+from app.core.config import settings
+
+# Engine setup
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    future=True,
+    connect_args={"check_same_thread": False} if settings.database_url.startswith("sqlite") else {}
+)
+
+# Session factory
+async_session_maker = async_sessionmaker(
+    engine, class_=AsyncSession, expire_on_commit=False, autoflush=False
+)
+
+Base = declarative_base()
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """Dependency for getting async database sessions."""
+    async with async_session_maker() as session:
+        yield session

app/core/logging.py

@@ -0,0 +1,22 @@
+import logging
+import sys
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure structured application logging."""
+    fmt = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter(fmt, datefmt="%Y-%m-%dT%H:%M:%S"))
+
+    root = logging.getLogger()
+    root.setLevel(level)
+    # Avoid duplicate handlers if called more than once (e.g. in tests)
+    if not root.handlers:
+        root.addHandler(handler)
+
+    # Quieten noisy libraries
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(name)

app/main.py

@@ -0,0 +1,56 @@
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.routes import health, resume, analysis
+from app.core.config import settings
+from app.core.logging import setup_logging
+
+setup_logging()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    """Startup / shutdown hook."""
+    # Ensure upload directory exists (config.py also does this at import time,
+    # but this is the canonical place for startup side-effects).
+    settings.upload_dir.mkdir(parents=True, exist_ok=True)
+    yield
+
+
+app = FastAPI(
+    title="AI Resume Reviewer API",
+    description=(
+        "Hybrid ATS-style resume analysis: rules + embeddings + LLM. "
+        "Phase 0/1 — ingestion and extraction only."
+    ),
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# ── CORS ──────────────────────────────────────────────────────────────────────
+# Allow the Vite dev server (8081) and any localhost variant during development.
+# In production, lock this to your actual frontend domain.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:8080",
+        "http://localhost:8081",
+        "http://localhost:3000",
+        "http://localhost:5173",
+        "http://127.0.0.1:8080",
+        "http://127.0.0.1:8081",
+        "http://127.0.0.1:5173",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+    expose_headers=["X-Session-Id"],
+)
+
+# ── Routers ───────────────────────────────────────────────────────────────────
+app.include_router(health.router, prefix="/api")
+app.include_router(resume.router, prefix="/api")
+app.include_router(analysis.router, prefix="/api")

app/models/analysis.py

@@ -0,0 +1,35 @@
+"""
+SQLAlchemy analysis model (Phase 5).
+"""
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.sqlite import JSON as SQLiteJSON
+from sqlalchemy.types import JSON
+
+from app.core.db import Base, engine
+
+
+def _new_id() -> str:
+    return f"an_{uuid.uuid4().hex[:12]}"
+
+
+# Handle JSON fallback for SQLite vs Postgres
+JsonType = SQLiteJSON if engine.url.drivername == "sqlite" else JSON
+
+
+class AnalysisRecord(Base):
+    __tablename__ = "analyses"
+
+    id = Column(String, primary_key=True, default=_new_id)
+    resume_id = Column(String, ForeignKey("resumes.id", ondelete="CASCADE"), nullable=False, index=True)
+    session_id = Column(String, index=True, nullable=False)
+    job_description = Column(Text, nullable=False)
+    target_role = Column(String, nullable=False)
+    result = Column(JsonType, nullable=False)
+    created_at = Column(
+        DateTime(timezone=True), 
+        default=lambda: datetime.now(timezone.utc), 
+        nullable=False
+    )

app/models/resume.py

@@ -0,0 +1,29 @@
+"""
+SQLAlchemy resume model (Phase 5).
+"""
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, DateTime, Integer, String, Text
+
+from app.core.db import Base
+
+
+def _new_id() -> str:
+    return f"res_{uuid.uuid4().hex[:12]}"
+
+
+class ResumeRecord(Base):
+    __tablename__ = "resumes"
+
+    id = Column(String, primary_key=True, default=_new_id)
+    session_id = Column(String, index=True, nullable=False)
+    file_name = Column(String, nullable=False)
+    file_path = Column(String, nullable=False)
+    extracted_text = Column(Text, nullable=False)
+    pages = Column(Integer, nullable=False)
+    uploaded_at = Column(
+        DateTime(timezone=True), 
+        default=lambda: datetime.now(timezone.utc), 
+        nullable=False
+    )

app/schemas/analysis.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+# ── Request ───────────────────────────────────────────────────────────────
+
+class AnalyzeRequest(BaseModel):
+    resume_id: str
+    job_description: str = Field(min_length=100, max_length=10_000)
+    target_role: str = ""
+
+
+# ── Response sub-types ────────────────────────────────────────────────────
+
+class ScoreWeights(BaseModel):
+    keyword_coverage: float = 0.30
+    semantic_similarity: float = 0.25
+    skills_overlap: float = 0.20
+    experience_alignment: float = 0.15
+    resume_quality: float = 0.10
+
+
+class ComponentBreakdown(BaseModel):
+    keyword_coverage: int
+    semantic_similarity: int
+    skills_overlap: int
+    experience_alignment: int
+    resume_quality: int
+
+
+class SectionNote(BaseModel):
+    section: str
+    status: Literal["strong", "ok", "weak", "missing"]
+    note: str
+    score: int
+
+
+class Recommendation(BaseModel):
+    priority: Literal["high", "medium", "low"]
+    category: str
+    message: str
+
+
+class BulletRewrite(BaseModel):
+    original: str
+    improved: str
+    reason: str
+
+
+# ── Full response ─────────────────────────────────────────────────────────
+
+class AnalyzeResponse(BaseModel):
+    analysis_id: str
+    overall_score: int
+    weights: ScoreWeights
+    components: ComponentBreakdown
+    matched_keywords: list[str]
+    missing_keywords: list[str]
+    weak_keywords: list[str]
+    section_notes: list[SectionNote]
+    recommendations: list[Recommendation]
+    bullet_rewrites: list[BulletRewrite]   # populated in Phase 4 (LLM)
+    role_fit_verdict: str
+    role_fit_summary: str
+    parsed_sections: dict                  # skills list, bullets, etc.
+    disclaimer: str = (
+        "ATS-style compatibility score (heuristic) — not an official ATS result."
+    )
+    latency_ms: int
+
+
+class AnalysisDetail(BaseModel):
+    analysis_id: str
+    resume_id: str
+    created_at: datetime
+    result: AnalyzeResponse

app/schemas/resume.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ResumeUploadResponse(BaseModel):
+    resume_id: str
+    file_name: str
+    pages_estimate: int
+    extraction_status: Literal["success", "pending", "failed"]
+
+
+class ResumeDetail(BaseModel):
+    resume_id: str
+    file_name: str
+    pages: int
+    extraction_status: Literal["success"]
+    uploaded_at: datetime
+    # Do NOT expose extracted_text in the response to keep payloads small.
+    # Phase 2 analysis endpoint will fetch the record server-side.
+    char_count: int