Python course Β· Module 12: Final Project
GitHub Portfolio
In this lesson6
A tracker who says "I saw a lion" but has no photo will not convince anyone. A recruiter looks at a CV the same way: "I know Python and FastAPI" is a claim, while a repository with a working project is proof. Your GitHub portfolio is your business card in the IT world, and many people judge a candidate by it before reading the cover letter. Let's show the world what you can do.
Repository Structure
The file layout makes the first impression. A clear structure says "this person knows what they are doing" before anyone opens the code:
ai-document-assistant/
βββ .github/
β βββ workflows/
β β βββ test.yml
β β βββ deploy.yml
β βββ ISSUE_TEMPLATE/
βββ app/
β βββ __init__.py
β βββ main.py
β βββ models/
β βββ services/
β βββ api/
β βββ config.py
βββ tests/
β βββ unit/
β βββ integration/
β βββ conftest.py
βββ docs/
β βββ architecture.md
β βββ api.md
βββ docker-compose.yml
βββ Dockerfile
βββ requirements.txt
βββ README.md
βββ LICENSE
βββ .env.exampleThe application code lives in app/, split into layers, the tests in tests/, split into unit and integration, and the CI workflows in .github/workflows/. The .env.example file contains variable names without real values, and you add .env itself to .gitignore. The LICENSE file says on what terms others may use your code. Without a license, full copyright applies, so formally nobody may copy or modify the code. For a portfolio project the MIT license is the simplest choice, and GitHub adds it in one click when you create the repository.
Environment Variables
Where does the application get its API key if it is not in the repository? From the .env file, read by the python-dotenv library. The load_dotenv() function loads variables from the file into the process environment, and os.getenv reads them:
import os
from dotenv import load_dotenv
load_dotenv() # loads variables from the .env file
api_key = os.getenv("API_KEY")If the variable is missing, os.getenv returns None instead of raising an exception. The code stays the same between your laptop and the server, only the environment changes.
Commit History
Recruiters also look at the history. The Conventional Commits convention standardizes the message format: the feat: prefix marks a new feature, fix: a bug fix, docs: documentation changes, chore: maintenance work. The typical flow is a new branch, changes, a commit, a Pull Request, and finally code review and merge:
git checkout -b feature/upload
git commit -m "feat: add API endpoint"You can also create the branch with the newer git switch -c feature/upload command, the effect is the same. Even in a solo project, Pull Requests show that you know how teamwork happens.
README Template
A portfolio README sells the project. The key elements are the title with a description, installation instructions, usage examples and the license. Badges at the top show the technologies and the test status:
# Project Name




> A short, catchy description of the project (1-2 sentences)
## Problem & Solution
**Problem:** What does the project solve?
**Solution:** How does it do it?
## Demo

[Live Demo](https://your-demo-url.com) | [Video](https://youtube.com/...)
## Tech Stack
- **Backend:** Python, FastAPI, SQLAlchemy
- **AI/ML:** LlamaIndex, OpenAI, Qdrant
- **Infrastructure:** Docker, GitHub Actions
- **Testing:** pytest, httpx
## Features
- Feature 1
- Feature 2
- Feature 3 (in progress)
## Architecture
```
[Architecture diagram]
```
## Quick Start
[Installation instructions]
## Performance
| Metric | Value |
|--------|-------|
| Response Time | <2s |
| Accuracy | 92% |
| Uptime | 99.9% |
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT Β© [Your Name](https://github.com/username)The "Problem & Solution" section is the most important, because it answers the question "why does this exist". The numbers in the Performance table are a place for your real measurements from evaluation, do not enter values you have not measured. The test badge takes its status from GitHub Actions, so green means the tests really pass.
GitHub Profile README
GitHub shows the README from the repository named after your username at the top of your profile. It is the place for a short introduction:
# Hi, I'm [Name]
Python Developer | AI/ML Enthusiast | Building cool stuff
## Current Projects
- [AI Document Assistant](link) - RAG system for document Q&A
- [Project 2](link) - Description
## Skills
```
Python ββββββββββββββββββββ 95%
FastAPI βββββββββββββββββββ 90%
ML/AI ββββββββββββββββ 80%
Docker βββββββββββββββ 75%
```
## GitHub Stats

## Contact
- LinkedIn: [link]
- Email: your@email.comSkill bars are decoration, take them with a pinch of salt. A link to a project someone can run works better. The github-readme-stats statistics come from an external service that is sometimes unavailable, so do not build your whole profile on it.
Tips
You can pin up to six repositories or gists on your profile, so choose your six best. Regular commits show activity, and on the green contribution graph consistency matters more than intensity. Every repository should have a README, always. If possible, add a live demo, because a working link convinces more than a description.
My advice: three polished projects with tests and a README beat twenty abandoned sketches. In the last lesson we will prepare for your career.
Remember: your portfolio is the photo album of your expedition, proof that you really crossed the savanna.
Code for this lesson: main.py
# ===========================================
# Safari Capstone: Project Setup & Configuration
# ===========================================
# Set up the complete project structure with
# configuration management and logging.
import logging
import json
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Optional
from datetime import datetime
# --- Configuration ---
@dataclass
class AppConfig:
"""Application configuration for the safari system."""
app_name: str = "Safari Wildlife Manager"
version: str = "1.0.0"
debug: bool = False
database_url: str = "sqlite:///safari.db"
api_port: int = 8000
log_level: str = "INFO"
max_observations_per_day: int = 1000
@classmethod
def from_dict(cls, data: dict) -> "AppConfig":
return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
def to_dict(self) -> dict:
return asdict(self)
# --- Logging setup ---
def setup_logging(config: AppConfig):
"""Configure application logging."""
logging.basicConfig(
level=getattr(logging, config.log_level),
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S"
)
logger = logging.getLogger(config.app_name)
logger.info(f"Logging initialized at {config.log_level} level")
return logger
# --- Data models ---
@dataclass
class Animal:
animal_id: str
species: str
name: str
weight_kg: float
region: str
status: str = "active"
tags: list[str] = field(default_factory=list)
created_at: str = field(default_factory=lambda: datetime.now().isoformat())
@dataclass
class Observation:
obs_id: str
animal_id: str
latitude: float
longitude: float
observer: str
notes: str = ""
timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
# --- Application bootstrap ---
config = AppConfig(debug=True, log_level="DEBUG")
logger = setup_logging(config)
print("=== Safari Project Setup ===")
print(f"App: {config.app_name} v{config.version}")
print(f"Debug: {config.debug}")
print(f"Database: {config.database_url}")
print(f"Port: {config.api_port}")
logger.info("Application started")
logger.debug("Debug mode is enabled")
# Create sample data
simba = Animal("LN-001", "Lion", "Simba", 195.0, "Savanna", tags=["alpha", "collared"])
obs = Observation("OBS-001", "LN-001", -2.33, 34.83, "Dr. Darwin", "Morning patrol sighting")
print(f"\nSample animal: {simba.name} ({simba.species})")
print(f"Sample observation: {obs.obs_id} at ({obs.latitude}, {obs.longitude})")
print(f"Config dict: {json.dumps(config.to_dict(), indent=2)}")
# TODO: Add environment-based configuration loading
# import os
# def load_config() -> AppConfig:
# env = os.getenv("APP_ENV", "development")
# config_data = {
# "debug": env == "development",
# "log_level": "DEBUG" if env == "development" else "INFO",
# "database_url": os.getenv("DATABASE_URL", "sqlite:///safari.db"),
# "api_port": int(os.getenv("PORT", "8000")),
# }
# return AppConfig.from_dict(config_data)
# TODO: Add a health check function
# def health_check(config: AppConfig) -> dict:
# return {
# "status": "healthy",
# "version": config.version,
# "database": "connected",
# "uptime_seconds": 0
# }
Docs entries used in this lesson
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What should a professional GitHub portfolio contain?
2. What is the purpose of the Conventional Commits convention?
Hands-on tasks in the game
- Click in order
Click the elements to build environment variable configuration:
- Horizontal ordering
Arrange the git commit command with a Conventional Commits message:
- Vertical ordering
Arrange the Git workflow steps in the correct order:
- Vertical ordering
Arrange the elements of a good README from the most important to the least important: