Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for CareerOS

What Inspired Us Students and early professionals face the same fragmented workflow: job boards in one tab, resume edits in another, LinkedIn in a third, and generic AI chatbots that don't understand their career context.

We asked a simple question:

What if your career had an operating system — one platform that orchestrates discovery, preparation, and application like an OS orchestrates apps?

That idea became Career OS: an AI-powered career platform where specialized agents handle the heavy lifting — job matching, resume optimization, cover letters, networking, and coaching — while the human stays in control.

The repository itself is a master foundation: not the final product, but the scaffolding many developers can clone and build on. That constraint shaped every architectural decision.

What We Learned

Foundation-first beats feature-first Building nine placeholder agents before any business logic felt counterintuitive, but it paid off. Every future agent inherits the same contract:

AgentOutput

f ( InputSchema , UserContext , GeminiModel ) AgentOutput=f(InputSchema, UserContext, GeminiModel) with logging, tracing, and error handling baked in — not bolted on later.

Monorepos need clear boundaries We split concerns into layers:

Layer Responsibility packages/types Contracts packages/ui Design system packages/ai-agents AI infrastructure apps/api Orchestration apps/web Experience The rule: shared code lives in packages; deployable code lives in apps.

Auth and roles are product decisions, not afterthoughts Clerk gave us fast authentication, but role-based access (admin, recruiter, student) had to be designed early. Permissions compound quickly once agents can read resumes and recruiters can view candidates.
Observability is part of the product For AI systems, you can't debug what you can't trace. Structured logs, request IDs, and integrations with Arize and Dynatrace aren't optional — they're how you answer: "Why did this agent give that recommendation?"

How We Built It Architecture We chose a Turborepo monorepo with a split stack:

Frontend: Next.js 15, TypeScript, TailwindCSS, ShadCN-style UI, React Query, Zustand, Framer Motion Backend: FastAPI, Python, Pydantic, Motor (async MongoDB) AI: Gemini 2.5 Pro + embeddings via a generic BaseAgent framework Search: Elasticsearch abstraction for keyword, semantic, hybrid, and vector search Auth: Clerk with protected routes and role guards Student / Recruiter Next.js Web Clerk Auth FastAPI MongoDB Elasticsearch AI Agent Engine Gemini 2.5 Pro Build sequence We worked in layers, bottom to top:

Tooling — ESLint, Prettier, Husky, Commitlint, CI/CD Shared packages — config, types, logger, auth, database, UI design system AI infrastructure — BaseAgent, registry, execution engine, nine placeholder agents API — versioned REST routes, middleware, rate limiting, DI Web shell — landing page, dashboard, settings, profile, error boundaries Infrastructure — Docker, GitHub Actions, Terraform for GCP Cloud Run Design system We centralized the visual language in packages/ui with a dark-first theme:

Primary: #2563EB Background: #0F172A Typography: Inter Reusable components (Button, Card, Modal, Sidebar, Dashboard Layout) plus Storybook so every team ships consistent UI.

Agent framework Each agent follows the same pattern:

@AgentRegistry.register class JobDiscoveryAgent(BaseAgent[JobDiscoveryInput, JobDiscoveryOutput]): name = "job_discovery" async def execute(self, input_data, user_id, trace_id=None): # Business logic goes here ... A conceptual match score for job ranking might look like:

job

α ⋅ skill_overlap + β ⋅ location_fit + γ ⋅ semantic_similarity Sjob=α⋅skill_overlap+β⋅location_fit+γ⋅semantic_similarity where α + β + γ = 1 α+β+γ=1. The foundation leaves α, β , γ α,β,γ for feature teams to tune — the pipeline is already there.

Challenges We Faced

Building for many developers, not one product The hardest requirement wasn't technical — it was scope discipline. This repo is a template, not a finished app. We had to ship real infrastructure (auth, DB, API, agents, CI/CD) without pretending the business logic was done.
Cross-language monorepo coordination TypeScript and Python don't share types natively. We mirrored contracts:

TypeScript types in packages/types Pydantic schemas in apps/api Agent input/output schemas in Python The lesson: the API contract is the source of truth — document it in docs/api.md and keep both sides aligned.

Clerk and CI builds Clerk keys are required for full auth, but CI and local builds shouldn't fail without them. We added graceful fallbacks: middleware and layout detect missing keys and degrade to link-based auth instead of crashing the build.
Python version fragmentation We targeted Python 3.12 in Docker and docs, but real dev machines often run 3.10. We relaxed requires-python to >=3.10 while keeping 3.12 for production images.
AI SDK churn Google's google.generativeai package is deprecated in favor of google.genai. We shipped a working GeminiProvider on the current SDK and left migration as a clear next step for agent implementers.
Enterprise structure vs. startup speed Every folder, lint rule, and doc file adds friction early and saves pain later. For a foundation repo meant to be cloned dozens of times, that tradeoff was intentional:

Foundation Value = Features Unblocked Setup Time × Consistency Foundation Value = Setup TimeFeatures Unblocked × Consistency

Career OS started from a simple observation: early-career job search is an orchestration problem, not a search problem. Students don't need another chatbot — they need an operating system that connects discovery, preparation, and application into one coherent workflow.

This repository is that OS kernel. The agents are stubbed, the pages are shells, but the pipes — auth, data, API, AI, search, observability, deployment — are real. Clone it, pick a feature, extend a BaseAgent, ship.

That's the whole point.