— — —

01 · Why Careers Are Broken

A career is one of the largest compounding decisions a person makes, and almost nobody manages it with actual data. The average professional's evidence base for "am I making the right move" is a resume that hasn't been meaningfully updated in a year, a LinkedIn profile optimized for keywords rather than signal, and a gut feeling about the market that's usually six months stale. Meanwhile the raw material for a genuinely informed decision — your actual shipped work, your skill trajectory, what the market is paying for right now, how your resume reads to an ATS before a human ever sees it — sits fragmented across a dozen disconnected surfaces. GitHub knows what you've built. LinkedIn knows who you know. Job boards know what's being hired for. Nothing connects the three.

02 · Why Existing Platforms Fail

Category	What It Optimizes For	What It Ignores
Resume builders	Formatting and templates	Whether the content is actually competitive for a target role
ATS checkers	Keyword-matching a single job description	Your broader skill trajectory and how it's evolving over time
Job portals	Volume of listings	Whether you're even a fit — and what would make you one
LinkedIn	Network visibility	Objective, code-level evidence of engineering ability

"Every one of these tools looks at a slice of your career. None of them look at the whole system."

03 · The CareerOS Vision

CareerOS is the intelligence layer that sits across all of it — resume, codebase, skills, and market — and turns fragmented signal into a single, coherent, actionable read on where you stand and what to do next.

It is not a resume builder. It is not an ATS checker. It is not a job portal.

Decision Engine Every module exists to answer one question better: what should you do next in your career, and why.

Evidence-Based Recommendations are grounded in your actual repos, resume content, and live market data — not generic advice.

Continuously Current Market Intelligence and GitHub Analysis pull live data, so your read on "where you stand" doesn't go stale.

04 · Product Overview — The Intelligence Modules

flowchart LR
    A["Resume"] --> E["Career Intelligence Engine"]
    B["GitHub Repositories"] --> E
    C["Skill Profile"] --> E
    D["Live Market Signals"] --> E
    E --> F["ATS Score + Gaps"]
    E --> G["Engineering Maturity Read"]
    E --> H["Skill Gap Map"]
    E --> I["AI-Generated Roadmap"]

    style E fill:#1D4ED8,stroke:#0F172A,color:#fff

Loading

05 · Resume Intelligence

Problem: Resumes are written once, under time pressure, and rarely re-evaluated against how they'll actually be read — by an ATS first, a recruiter second. Solution: Resume Intelligence parses structure and content, then uses Gemini to evaluate clarity, impact-language, and role alignment — not just keyword presence.

Note Engineering decision: parsing is separated from scoring. The parser produces a structured representation of the resume; scoring logic operates on that structure, not raw text — so scoring rubrics can evolve without touching the parsing layer.

06 · ATS Analyzer

Runs the parsed resume against target-role requirements and returns a concrete, explainable score rather than an opaque number — surfacing which sections are hurting parseability (formatting, missing structured fields) versus which are hurting content match (missing skills, weak impact statements). The distinction matters: the fix for a formatting problem and a content problem is completely different, and collapsing them into one score hides that.

07 · GitHub Analyzer

Connects to the live GitHub API to analyze a user's actual repositories — commit patterns, language distribution, project structure, and activity consistency — and turns that into an Engineering Maturity read that a resume bullet point can't fake. Why this matters: a resume says what you claim to have built. GitHub shows what you actually shipped. CareerOS treats the second as the higher-trust signal and reconciles the two.

flowchart TD A["GitHub API"] --> B["Repo Metadata + Commits"] B --> C["Language / Activity Analysis"] C --> D["Engineering Maturity Score"] D --> E["Reconciled with Resume Claims"] style D fill:#2563EB,stroke:#0F172A,color:#fff Loading

08 · Skill Gap Analysis & Market Intelligence

Skill Gap Analysis Compares your current, evidenced skill set (from resume + GitHub Analyzer) against the skill profile of your target role, and surfaces the delta as a ranked list — not a wall of "skills to learn."

Market Intelligence Pulls current market signal on what's being hired for in your target roles, so the skill gap isn't measured against a static, potentially outdated rubric — it's measured against what's in demand right now.

09 · AI Roadmap Generator

Synthesizes the outputs of every prior module — ATS score, Engineering Maturity, Skill Gap, Market Intelligence — into a single, sequenced roadmap: what to fix first, what to build next, and what to learn, ranked by impact on your target role rather than presented as an undifferentiated list. Engineering decision: the roadmap generator runs last in the pipeline and takes the outputs of the other modules as its input — not raw data — so its recommendations are always internally consistent with what the rest of the platform already found.

10 · Dashboard Preview

_{▲ Placeholder — record a walkthrough of a real analysis run (resume upload → ATS score → roadmap) and replace this GIF.}

11 · System Architecture

flowchart TB
    subgraph Client["Client Layer"]
        UI["React Frontend<br/>Dashboard · Upload · Reports"]
    end

    subgraph Backend["Application Layer"]
        FL["Flask<br/>Auth · Resume Upload · Orchestration"]
        FA["FastAPI Microservice<br/>ATS Scoring · GitHub Analysis · AI Pipeline"]
    end

    subgraph External["External Signal"]
        GH["GitHub API"]
        GEM["Gemini API"]
    end

    UI -->|"REST"| FL
    FL -->|"internal call"| FA
    FA --> GH
    FA --> GEM
    GEM --> FA
    FA -->|"structured result"| FL
    FL -->|"JSON"| UI

    style FA fill:#1D4ED8,stroke:#0F172A,color:#fff
    style UI fill:#2563EB,stroke:#0F172A,color:#fff

Loading

Frontend Architecture

React, structured around a dashboard-first information architecture — upload/input surfaces feed into a persistent results dashboard rather than a linear wizard, so a user can revisit any prior analysis (ATS score, GitHub read, roadmap) without re-running the pipeline.

Backend Architecture

Flask handles the application concerns — auth, file upload, request orchestration — while the analysis-heavy work is isolated in a FastAPI microservice: ATS scoring, GitHub API integration, and the Gemini-backed AI pipeline. This split means the compute- and latency-variable analysis work can be scaled or rate-limited independently of the core app's request path — important given GitHub API calls carry their own rate limits and Gemini calls carry their own latency profile.

12 · Technology Stack

Layer	Technology	Purpose
Frontend	React	Dashboard-first UI — resume upload, analysis reports, roadmap view
Application Backend	Flask	Auth, file handling, request orchestration
Analysis Microservice	FastAPI	ATS scoring, GitHub Analyzer, AI pipeline — isolated for independent scaling
External Signal	GitHub API	Live repository data for the Engineering Maturity read
LLM	Google Gemini	Resume evaluation, roadmap synthesis, content-quality scoring
Hosting	Vercel	Production deployment

Folder Structure

careeros/
├── client/                     # React frontend
│   ├── src/
│   │   ├── components/          # Dashboard, upload, report cards
│   │   ├── pages/                 # Route-level views
│   │   └── services/               # API client layer
├── server/
│   ├── flask_app/                # Auth, upload endpoints, orchestration
│   └── ai_service/                # FastAPI microservice
│       ├── ats/                    # ATS scoring logic
│       ├── github_analyzer/         # GitHub API integration + scoring
│       ├── roadmap/                  # Roadmap synthesis
│       └── main.py
├── requirements.txt
└── package.json

Note

Placeholder — confirm this matches your actual repo layout before publishing; adjust to your real package structure.

13 · Environment Variables

Warning

Placeholder — fill in with your actual required variables before publishing. Never commit real values.

Variable	Purpose	Required
GEMINI_API_KEY	Google Gemini API access for resume evaluation and roadmap generation	Yes
GITHUB_API_TOKEN	Authenticated GitHub API access for the GitHub Analyzer	Yes
FLASK_SECRET_KEY	Session/auth signing	Yes
FASTAPI_SERVICE_URL	Internal endpoint the Flask app calls for analysis	Yes

14 · Security

• API keys (Gemini, GitHub) are held server-side only — never exposed to the React client
• GitHub Analyzer requests are scoped to read-only repository access
• Resume uploads should be validated for file type/size before parsing

Warning

Placeholder — confirm actual data retention policy for uploaded resumes and analysis history before publishing.

15 · Performance & Scalability

Concern	Approach
Analysis latency	Isolated FastAPI microservice so GitHub/Gemini calls don't block the core Flask request path
GitHub API rate limits	Authenticated requests (higher rate limit) + response caching per repo to avoid redundant calls
Horizontal scale	Flask and the FastAPI microservice are deployed and scaled independently

16 · Roadmap

• Resume Intelligence + ATS Analyzer
• GitHub Analyzer with live API integration
• Skill Gap Analysis + Market Intelligence
• AI Roadmap Generator
• Historical tracking — trend lines across repeated analyses over time
• Team/organization view for engineering managers
• Interview-readiness module, grounded in the same evidence base

17 · Contributing

1. Fork the repository and create a feature branch (feat/your-feature)
2. If adding a new intelligence module, follow the pattern in §09 — consume other modules' outputs, not raw data, to keep recommendations internally consistent
3. Document any new external API dependency and its rate-limit/caching behavior
4. Open a PR describing the product impact, not just the code diff

18 · Developer

Bhagavan — @thenameisbhagavan

19 · License

Distributed under the MIT License. See LICENSE for details.

_{Fragmented signal, in. A clear next move, out. — CareerOS}