04/Job Platform & AggregatorFull-Stack System Architect2024

KarStack

پلتفرم کاریابی با معماری Monorepo شامل پنل‌های Next.js و API نوشته شده با FastAPI.

استک تکنولوژیNEXT.JSFASTAPIPYTHONSQLMODELTAILWINDTURBOREPORADIX-UI

سورس بسته

مرور کلی

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

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.

اجزای سیستم

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.

جریان داده و اجرا

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.

قابلیت‌های کلیدی

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.

تصمیمات فنی و مصالحه‌ها

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.

نحوه استفاده و راه‌اندازی

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

بازگشت به پروژه‌هاسورس بسته