This is your capstone project — the final proof that you can use Claude Code and MCP to build something real, from empty folder to live URL. You'll build a functional full-stack application using every major technique from this course: Claude Code for development, MCP servers for data access, CLAUDE.md for project memory, and GitHub Actions for automated deployment. The project is a Pakistani Freelancer Rate Calculator — a useful tool you can actually publish, share, and potentially monetize.

Full-Stack Architecture

Here is the complete system you will build:

+--------------------------------------------------+
|                   BROWSER (User)                  |
|   Tailwind CSS + Jinja2 Templates + Fetch API     |
+---------------------------+----------------------+
                            |
                       HTTP Requests
                            |
+---------------------------v----------------------+
|                  FastAPI Backend                  |
|                                                  |
|  GET /           --> Serves frontend HTML         |
|  POST /calculate --> Rate engine + DB write       |
|  GET /stats      --> Admin panel (X-Admin-Key)    |
|  GET /health     --> {"status": "ok"}             |
|                                                  |
+--------+-----------------+-----------+-----------+
         |                 |           |
         v                 v           v
+----------------+ +-------------+ +----------------+
| calculator.py  | | models.py   | | db.py          |
| Rate formula   | | Pydantic v2 | | SQLite CRUD    |
| Skill premiums | | Validation  | | submissions    |
+----------------+ +-------------+ +--------+-------+
                                             |
                                    +--------v-------+
                                    |  rates.db      |
                                    |  (SQLite)      |
                                    +--------+-------+
                                             |
                              MCP Protocol (stdio)
                                             |
                                    +--------v-------+
                                    | mcp_server.py  |
                                    | query_rates    |
                                    | skill_distrib  |
                                    | avg_rates      |
                                    +--------+-------+
                                             |
                                    +--------v-------+
                                    |  Claude Code   |
                                    |  (Analytics)   |
                                    +----------------+

+--------------------------------------------------+
|              GitHub Actions CI/CD                 |
|  push --> pytest --> deploy to Vercel/VPS         |
+--------------------------------------------------+

Section 1: The Project Spec

Pakistani Freelancer Rate Calculator — a web app where Pakistani freelancers can enter their skills, experience level, and target monthly income to get a recommended hourly/project rate in both PKR and USD.

Features:

1. Rate calculation engine (skill + experience + market data -> recommended rate)
2. Market comparison (show how the recommended rate compares to Upwork/Fiverr market data for Pakistan)
3. SQLite database storing rate submissions (anonymous) for aggregate insights
4. Admin panel (protected by API key) to view submission trends
5. MCP server for the database so Claude can analyze rate trends

Tech stack:

• Backend: FastAPI + SQLite
• Frontend: Simple HTML + Tailwind CSS (served by FastAPI)
• MCP: Database MCP server for analytics
• Deployment: Vercel (backend) or Contabo VPS (self-hosted)

Section 2: The Claude Code Build Session

This is the core of the capstone. Follow each step carefully. Every prompt below is something you type directly into Claude Code.

Step 1 — CLAUDE.md First: Before writing a single line of code, create your CLAUDE.md:

## Project: Pakistani Freelancer Rate Calculator
A web tool that helps Pakistani freelancers on Upwork/Fiverr determine
their optimal hourly and project rates in PKR and USD.

## Tech Stack
- Python 3.12, FastAPI, SQLite, Pydantic v2
- Frontend: Jinja2 templates + Tailwind CSS (CDN)
- Deployed: Vercel serverless or Contabo VPS

## Rate Calculation Logic
Base rate formula:
- Junior (0-2 years): $5-15/hour, PKR 1,400-4,200
- Mid (2-5 years): $15-35/hour, PKR 4,200-9,800
- Senior (5+ years): $35-80/hour, PKR 9,800-22,400
- Multiply by skill premium: AI/ML (+40%), Web Dev (+20%), Design (+10%)

## API Endpoints
POST /calculate — input: skill, experience, target_income → output: rate_pkr, rate_usd, market_comparison
GET /stats — returns aggregate stats (admin only, requires X-Admin-Key header)
GET / — serves the frontend HTML

Step 2 — Build the Backend with Claude Code: Open Claude Code in your empty project directory. With your CLAUDE.md in place, you can work efficiently. Here is the exact sequence of prompts and what Claude will produce:

Prompt 2a — Data models and core endpoint:

You: "Build the FastAPI backend based on the CLAUDE.md spec. Start with
the data models and the /calculate endpoint."

Expected output: Claude creates 4 files:

• models.py — Pydantic models: RateRequest(skill, experience_years, target_monthly_pkr) and RateResponse(hourly_pkr, hourly_usd, project_rate_pkr, market_percentile, comparison_text)
• calculator.py — The rate formula with skill premiums dict and experience tier logic
• db.py — SQLite connection, create_tables(), save_submission(), get_all_submissions()
• main.py — FastAPI app with POST /calculate wired up

What to check before moving on: Open calculator.py and verify the rate ranges match your CLAUDE.md. Claude sometimes invents its own numbers — correct them if they differ. Also confirm PKR/USD conversion uses a realistic rate (around PKR 278-285 per USD as of 2026).

Prompt 2b — Frontend:

You: "Now build the frontend HTML page that calls the /calculate endpoint
via JavaScript fetch and displays the results with a nice Tailwind UI.
Include a skill dropdown (AI/ML, Web Dev, Mobile Dev, Design, Data Science,
Content Writing, Video Editing), an experience slider (0-15 years), and a
target income input field in PKR."

Expected output: Claude creates templates/index.html with:

• A clean form with the skill dropdown, experience range slider, and PKR input
• A results card that appears after calculation showing hourly PKR, hourly USD, monthly projection, and a market comparison bar
• Responsive layout that works on mobile (important — many Pakistani freelancers browse on phone)

What to check: Open the HTML in your browser. Make sure the fetch URL points to /calculate (not http://localhost:8000/calculate — relative URLs are more portable). Verify the Tailwind CDN link is present in the <head>.

Prompt 2c — Admin stats panel:

You: "Add the GET /stats endpoint (protected by X-Admin-Key header) that
returns: total submissions, average rate by skill, most common experience
level, and top 5 highest rates. Also add a simple admin.html page that
calls this endpoint."

Expected output: Claude adds the stats endpoint to main.py, creates templates/admin.html, and adds a header check that returns 403 if the key is wrong.

Prompt 2d — MCP server:

You: "Add the database MCP server so I can analyze rate submission trends.
Use the pattern from Module 4. Include tools for: query_rates (with filters),
get_skill_distribution, get_average_rates, and get_submission_timeline."

Expected output: Claude creates mcp_server.py with 4 tools registered via the MCP SDK. Each tool queries rates.db and returns structured JSON.

What to check: Run the MCP server locally and test with Claude Code by adding it to your .claude.json. Ask Claude: "How many submissions are in the database?" — it should use the MCP tool to answer.

Step 3 — Testing with Claude: Ask Claude to write tests for the core calculation logic:

You: "Write pytest tests for the rate calculator. Test: junior AI developer,
senior web developer, mid-level designer — verify each returns rates in
the expected ranges. Also test edge cases: 0 years experience, negative
target income (should raise validation error), and missing skill field."

Expected output: Claude creates tests/test_calculator.py with at minimum 6 test functions. The edge case tests are important — they catch bugs that would embarrass you in production.

Run the tests immediately:

You: "Run the tests and fix any failures."

Claude will execute pytest -v, see any failures, read the error messages, and fix them. This is the Claude Code loop at its most powerful — test, fail, fix, repeat, all within one conversation.

Step 4 — CI/CD Setup:

You: "Create a GitHub Actions workflow that runs tests on push and deploys
to Vercel on merge to main. Use the VERCEL_TOKEN secret for deployment."

Claude generates the complete .github/workflows/ci-deploy.yml based on the patterns from lesson 5.2. Review it to confirm it has separate test and deploy jobs, and that the deploy job has needs: test so it only deploys if tests pass.

Section 3: The Deployment Checklist

Before you call this project "done," run through this checklist:

Production Readiness:
[ ] All secrets in environment variables (never hardcoded)
[ ] /health endpoint returns {"status": "ok"} for monitoring
[ ] Input validation on all endpoints (Pydantic handles this)
[ ] Rate limiting on /calculate (to prevent abuse)
[ ] Error responses return JSON, not HTML stack traces
[ ] CORS configured for your frontend domain
[ ] SQLite database backed up (or switched to PostgreSQL for real scale)

CLAUDE.md is up to date:
[ ] Architecture section reflects final file structure
[ ] All API endpoints documented
[ ] Deployment method documented
[ ] Current Work section updated with what's done and what's next

CI/CD verified:
[ ] Push to develop --> tests run --> green checkmark
[ ] Merge to main --> tests run --> deploy triggers --> health check passes
[ ] API secrets added to GitHub Secrets (not in YAML)

Pakistan Case Study: Hamza from Lahore

Hamza Raza, 24, was a self-taught Python developer in Lahore working low-paying gigs on Fiverr — PKR 5,000-10,000 per project, mostly web scraping scripts. He had no CS degree (BCom from Punjab University) and no portfolio beyond his Fiverr profile.

He completed this course in February 2026 and built the Pakistani Freelancer Rate Calculator as his capstone. But he did not stop at the basic spec. Here is what he added:

• City-specific rates — Karachi, Lahore, Islamabad, and Faisalabad each have different cost-of-living multipliers that adjust the recommended rate
• Currency toggle — PKR, USD, AED, and GBP (covering the main markets Pakistani freelancers serve)
• Anonymous benchmarking — after 200 submissions, users could see where their rate falls compared to others with similar skills

He deployed it on Vercel's free tier at pk-rate-calc.vercel.app and shared it on three Pakistani tech communities: the Pakistan Developer Community Discord, the PakTech LinkedIn group, and r/PakistanTech on Reddit.

Results in 60 days:

• 500+ unique users (mostly from LinkedIn shares — other freelancers found it genuinely useful)
• 1,200+ rate calculations performed
• The post where he shared it got 47 comments and 200+ reactions on LinkedIn

The job offer: A Lahore-based SaaS startup (serving the Middle East market) saw his LinkedIn post. They were looking for a developer comfortable with AI tooling, FastAPI, and rapid prototyping. They interviewed him, asked him to walk through his capstone code on GitHub, and offered him a full-time role at PKR 200,000/month — a 10x increase from his Fiverr income.

What made the difference: It was not the calculator itself. It was the combination: clean GitHub repo with CI/CD, a live deployed URL, an MCP server showing he understood modern AI tooling, and a CLAUDE.md that proved he could document and plan before coding. The hiring manager told him: "We have 50 applicants who say they know AI. You are the only one who showed a production system."

The lesson: your capstone is not homework. It is a business card.

Your Deliverable

When you complete this capstone, you should have:

1. A live URL (even Vercel's free tier .vercel.app domain works) where the calculator runs
2. A GitHub repository with your code, CLAUDE.md, and CI/CD workflow
3. An MCP server you can run locally to analyze the calculator's database with Claude
4. A 2-minute demo — record your screen showing: the live site, making a calculation, running Claude Code with the MCP server to query the database

This is your portfolio piece. Add it to your Upwork profile, your GitHub README, and your LinkedIn. It demonstrates you can: build a full-stack app, use Claude Code professionally, implement MCP, and deploy with CI/CD. In the Pakistani tech market of 2026, this skill set commands PKR 150,000-300,000/month for senior roles.

What to Put in Your Portfolio

Building the capstone is half the work. Presenting it correctly to employers and clients is the other half. Here is exactly how to package this project:

GitHub README structure: Your repo README should follow this order — recruiters spend 8 seconds scanning before deciding to look deeper:

1. One-line description — "Pakistani Freelancer Rate Calculator — helps 500+ freelancers price their skills correctly"
2. Live demo link — the Vercel URL, clickable, at the top
3. Screenshot — one clean screenshot of the calculator in action (not a wall of screenshots)
4. Tech stack badges — FastAPI, Python, SQLite, Tailwind, Vercel (use shields.io badges)
5. Features list — 4-5 bullet points, each starting with a verb ("Calculates," "Compares," "Stores," "Analyzes")
6. Architecture diagram — the ASCII diagram from this lesson or a clean draw.io version
7. How to run locally — pip install -r requirements.txt && uvicorn main:app
8. MCP server instructions — shows you understand cutting-edge AI tooling

Upwork profile integration: In your Upwork profile summary, add a line like: "Built and deployed a full-stack FastAPI application with CI/CD pipeline and MCP server integration — [link to live app] | [link to GitHub]." On Upwork, clients scan for proof of shipping. A live URL beats 10 paragraphs of self-description.

LinkedIn post formula: Write a post with this structure (this format consistently gets high engagement in Pakistani tech circles):

• Line 1: Bold claim or result ("I built a full-stack app in 4 hours using Claude Code.")
• Lines 2-5: What you built and why it matters
• Lines 6-8: One specific thing you learned or that surprised you
• Line 9: Call to action ("Try it here: [link]. Feedback welcome.")
• Hashtags: #PakistanTech #AItools #ClaudeCode #Freelancing #BuildInPublic

Client proposal attachment: When sending proposals on Upwork or Fiverr, attach a 1-page PDF "Project Case Study" with: problem statement, solution, tech stack, architecture diagram, and live URL. This positions you as a professional, not a code monkey. Clients pay 3-5x more for developers who communicate like consultants.

Interview walkthrough prep: Practice explaining your capstone in 3 minutes covering: (1) what problem it solves, (2) one architectural decision you made and why, (3) how CI/CD works in your pipeline, (4) what you would improve if you had another week. This covers the four things technical interviewers care about: problem-solving, architecture, DevOps awareness, and self-reflection.

Exercise 1: Complete the capstone project. Build, test, and deploy the Rate Calculator. Use Claude Code for at minimum 80% of the code generation. Document any places where you had to correct Claude's output — this is valuable learning data about Claude's limitations.

Exercise 2: After building, analyze your MCP database with Claude. Ask: "What is the average recommended rate by skill category? What experience level is most common in submissions? What's the highest rate submitted?" Generate a brief insights report — this demonstrates MCP analytics in a real use case.

Exercise 3: Write a LinkedIn post (in your own voice) sharing what you built, what you learned, and what surprised you about using Claude Code for the full build. Tag it with Pakistani tech community hashtags. This post starts building your reputation as an AI-native developer — which compounds into consulting opportunities, job offers, and client referrals.

Exercise 4: Add one original feature that is not in the spec. Ideas: a "Rate History" chart showing how Pakistani freelancer rates have changed over 12 months, a "Compare with India" toggle that shows rate differences across the border, a Telegram bot that returns your rate via /rate ai_ml 3 years, or a dark mode toggle. The point is to demonstrate initiative — employers and clients want developers who think beyond the ticket. Build it, deploy it, and add it to your GitHub README as a "Bonus Feature" section.

Key Takeaways

• The CLAUDE.md-first approach is the professional standard for Claude Code projects — writing it before code prevents architectural drift and keeps Claude aligned with your intent throughout the build
• Real projects require iteration — your first Claude output will need fixes, and that's expected. The skill is in directing Claude toward the right solution efficiently, not expecting perfection on the first prompt
• A GitHub repository with CI/CD and a live URL is the minimum for a credible portfolio project in 2026 — static screenshots are not sufficient to demonstrate technical capability
• The compound value of this course is not any single lesson — it's the combination: Claude Code velocity + MCP server depth + CI/CD reliability + CLAUDE.md consistency = a developer who ships production software systematically
• Always verify Claude's output against your spec before moving to the next step — catching a wrong rate formula in calculator.py takes 30 seconds, but catching it after deployment takes 30 minutes of debugging and redeploying
• Your capstone is a living project, not a submission — keep the Vercel URL running, update the database, and reference it in every job application and client proposal for the next 6 months
• The MCP server is your secret weapon in interviews — most candidates in 2026 can talk about AI tools, but very few can demonstrate a working MCP integration that lets Claude query a real database. This differentiator alone justifies the time invested in this course
• Packaging and presentation matter as much as code quality — a clean README, a live demo link, and a 2-minute walkthrough video convert more interviews into offers than raw technical skill alone