04/Job Platform & AggregatorFull-Stack System Architect2024

KarStack

A job hunting platform featuring a Turborepo monorepo with Next.js web and dashboard applications, powered by a Python FastAPI and SQLModel backend.

Tech StackNEXT.JSFASTAPIPYTHONSQLMODELTAILWINDTURBOREPORADIX-UI

Closed source

Overview

Problem & solution scope

KarStack is an end-to-end recruitment platform and career intelligence aggregator. It continuously crawls and normalizes tech job postings across Iranian hiring boards into a centralized database, offering advanced search filters (tech stack, salary range, remote status, seniority), applicant tracking, and administration tools.

System Architecture

System architecture

Polyglot Monorepo with Relational Ingestion Engine

Structured as a Turborepo monorepo housing a Python FastAPI REST API with SQLModel/PostgreSQL and three Next.js applications (Public Web, User Dashboard, Admin Dashboard). Shared UI design tokens, Radix UI primitives, and TypeScript types are managed in shared workspace packages.

System Components

KarStack API Engine

Python 3.14 / FastAPI / SQLModel / PostgreSQL

Implements business logic, job normalization schemas, search indexing, and JWT-authenticated candidate APIs.

Shared UI Package (@packages/ui)

React / Radix UI / Tailwind CSS v4

Single source of truth for design tokens, typography, form inputs, and modal components across web apps.

Public Web Portal

Next.js App Router

High-performance search interface with server-side rendered job listings, SEO-optimized company profiles, and quick filters.

Candidate & Admin Dashboards

Next.js Client Dashboards

Role-based portals for saved searches, application status management, and catalog scraper health monitoring.

Data & Execution Flow

Job Ingestion & Parsing

Scheduled workers fetch listings from tech hiring boards and parse raw HTML into structured SQLModel entities.

Tagging & Normalization

Extracts required tech stacks (e.g. Python, React, Docker), salary brackets, and remote work classifications.

Relational Indexing

Persists to PostgreSQL using psycopg3 driver with optimized indexes on skills, location, and date.

Multi-App Delivery

Public site serves SEO-ready job pages while dashboards consume authenticated endpoints for candidate tracking.

Key Capabilities

Engineered capabilities

[01]

Structured Job Normalization: Unifies disparate posting formats into a clean schema with parsed skill requirements.

[02]

Multi-Workspace Monorepo: Single repository coordinating 3 Next.js applications and shared UI design system packages.

[03]

Strict Postgres Target: Built specifically for PostgreSQL 17 with psycopg3 driver for maximum query performance.

[04]

Two-Stack Docker Architecture: Separate dev and production compose configurations with healthchecks and auto-migrations.

[05]

Dual Dashboard Capabilities: Dedicated portals for job-seeker workflows and administrative oversight.

Technical Decisions & Trade-offs

Engineering trade-offs

SQLModel over Raw SQLAlchemy

Combines Pydantic data validation with SQLAlchemy ORM models, eliminating type duplication between API input schemas and database tables.

Single Next.js Dockerfile for Multiple Apps

Designed a multi-target Dockerfile that builds all three frontend workspaces in one pass via Turborepo caching.

Implementation & Usage

Docker Dev Stack Initialization

// bashsnippet

docker compose -f docker-compose.dev.yml up -d --build

# Web app running on http://localhost:3000
# Admin dashboard on http://localhost:3001
# API engine on http://localhost:8000

Back to ProjectsClosed source