feat: Setup complete FastAPI backend skeleton

apps/backend/.gitignore

@@ -1,5 +1,5 @@
-.jobs-api-venv/
-
+*env/
+*venv/
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

apps/backend/requirements.txt

@@ -2,8 +2,9 @@ fastapi
 uvicorn[standard]
 SQLAlchemy
 psycopg2-binary
-pydantic
+alembic
 pydantic[email]
+pydantic-settings
 passlib[bcrypt]
 python-dotenv
 requests==2.32.1

apps/backend/run.sh

@@ -1 +1 @@
-uvicorn main:app --reload
+uvicorn src.main:app --reload

apps/backend/src/api/deps/db.py

@@ -0,0 +1,8 @@
+from ...db.session import SessionLocal
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

apps/backend/src/api/deps/pagination.py

@@ -0,0 +1,50 @@
+from fastapi import Query, HTTPException
+from math import ceil
+from typing import Optional
+from ...core.constants import Constants
+
+
+async def pagination_params(
+    page: Optional[int] = Query(1, ge=1, description='Page number (1-indexed)'),
+    per_page: Optional[int] = Query(
+        Constants.DEFAULT_PAGE_SIZE, ge=1, le=Constants.MAX_PAGE_SIZE, description='Items per page'
+    ),
+):
+    '''
+    Common dependency to extract pagination parameters from query string.
+    Example: ?page=2&per_page=20
+    '''
+    return {'page': page, 'per_page': per_page}
+
+
+def paginate_query(query, pagination: dict):
+    '''
+    Apply pagination to an SQLAlchemy query using page & per_page.
+    '''
+    page = pagination.get('page', 1)
+    per_page = pagination.get('per_page', Constants.DEFAULT_PAGE_SIZE)
+
+    if per_page > Constants.MAX_PER_PAGE:
+        raise HTTPException(status_code=400, detail=f'per_page cannot exceed {Constants.MAX_PER_PAGE}')
+
+    offset = (page - 1) * per_page
+    return query.limit(per_page).offset(offset)
+
+
+def build_paginated_response(items: list, total: int, page: int, per_page: int):
+    '''
+    Build a consistent paginated response payload with metadata.
+    '''
+    total_pages = ceil(total / per_page) if total > 0 else 1
+
+    return {
+        'meta': {
+            'total': total,
+            'page': page,
+            'per_page': per_page,
+            'total_pages': total_pages,
+            'has_next': page < total_pages,
+            'has_prev': page > 1,
+        },
+        'results': items,
+    }

apps/backend/src/api/v1/routes/jobs.py

@@ -0,0 +1,39 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from uuid import UUID
+
+from ....schemas import job as schemas
+from ...deps.db import get_db
+from ...deps.pagination import pagination_params
+from ....services import job as job_service
+
+router = APIRouter(prefix='/jobs')
+
+# @router.post('/', response_model=schemas.JobBase)
+# def create_job(job_in: schemas.JobBase, db: Session = Depends(get_db)):
+#     return job_service.create_job(db, job_in)
+
+# @router.get('/{job_id}', response_model=schemas.JobBase)
+# def get_job(job_id: UUID, db: Session = Depends(get_db)):
+#     db_job = job_service.get_job(db, job_id)
+#     if not db_job:
+#         raise HTTPException(status_code=404, detail='Job not found')
+#     return db_job
+
+@router.get('/', response_model=list[schemas.JobBase])
+def list_jobs(query: str | None = None, pagination: dict = Depends(pagination_params), db: Session = Depends(get_db)):
+    return job_service.get_jobs(db, pagination, query)
+
+# @router.put('/{job_id}', response_model=schemas.JobBase)
+# def update_job(job_id: UUID, job_update: schemas.JobBase, db: Session = Depends(get_db)):
+#     db_job = job_service.update_job(db, job_id, job_update)
+#     if not db_job:
+#         raise HTTPException(status_code=404, detail='Job not found')
+#     return db_job
+
+# @router.delete('/{job_id}')bs
+# def delete_job(job_id: UUID, db: Session = Depends(get_db)):
+#     success = job_service.delete_job(db, job_id)
+#     if not success:
+#         raise HTTPException(status_code=404, detail='Job not found')
+#     return {'detail': 'Job deleted'}

apps/backend/src/core/config.py

@@ -0,0 +1,14 @@
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # Database
+    DATABASE_URL: str
+    BACKEND_CORS_ORIGINS: list[str] = []
+    LOG_LEVEL: str = 'INFO'
+
+    class Config:
+        env_file = '.env'
+        case_sensitive = True
+
+
+settings = Settings()

apps/backend/src/core/constants.py

@@ -0,0 +1,3 @@
+class Constants:
+    DEFAULT_PAGE_SIZE: int = 10
+    MAX_PAGE_SIZE: int = 100

apps/backend/src/db/base_class.py

@@ -0,0 +1,9 @@
+from datetime import datetime
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime
+
+class Base(DeclarativeBase):
+    id: Mapped[int] = mapped_column('id', primary_key=True, autoincrement=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    __abstract__ = True

apps/backend/src/db/session.py

@@ -0,0 +1,17 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from ..core.config import settings
+
+DATABASE_URL = settings.DATABASE_URL
+
+engine = create_engine(
+    DATABASE_URL,
+    echo=settings.LOG_LEVEL == 'debug',
+    future=True
+)
+
+SessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=engine
+)

apps/backend/src/main.py

@@ -0,0 +1,18 @@
+from fastapi import FastAPI
+from .api.v1.routes import jobs
+from .models import company, job, skill, user
+from .db.base_class import Base
+from .db.session import engine
+
+# Ensure tables are created
+Base.metadata.create_all(bind=engine)
+
+app = FastAPI(title='JobApplica API')
+
+api_v1_prefix = '/api/v1'
+
+app.include_router(jobs.router, prefix=api_v1_prefix, tags=['Jobs'])
+# app.include_router(users.router, prefix=api_v1_prefix, tags=['Users'])
+# app.include_router(plugins.router, prefix=api_v1_prefix, tags=['Plugins'])
+# app.include_router(auth.router, prefix=api_v1_prefix, tags=['Auth'])
+# app.include_router(health.router, prefix=api_v1_prefix, tags=['Health'])

apps/backend/src/models/company.py

@@ -0,0 +1,20 @@
+# src/models/company.py
+from sqlalchemy import String, Integer
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from ..db.base_class import Base
+
+class Company(Base):
+    __tablename__ = 'companies'
+    name: Mapped[str] = mapped_column(String(100), nullable=False, unique=True)
+    website: Mapped[str] = mapped_column(String(255), nullable=True)
+    email: Mapped[str] = mapped_column(String(255), nullable=True)
+    location: Mapped[str] = mapped_column(String(255), nullable=False)
+    size: Mapped[int] = mapped_column(Integer, nullable=True)
+    headquarters: Mapped[str] = mapped_column(String(255), nullable=True)
+    founded_year: Mapped[int] = mapped_column(Integer, nullable=True)
+    industry: Mapped[str] = mapped_column(String(255), nullable=True)
+    description: Mapped[str] = mapped_column(String(500), nullable=True)
+
+    def __repr__(self):
+        return f"<Company id={self.id} name='{self.name}'>"