⏱️ Pomora — Focus. Build. Grow.

Harvard CS50W Final Project

🧭 Overview

Pomora is a full-stack productivity web application built as the Final Project of
Harvard's CS50 Web Programming with Python and JavaScript.

It combines task management and the Pomodoro technique into one elegant system —
helping users stay focused, analyze their productivity, and manage projects effectively.

🎯 Project Concept

“Focus for 25 minutes. Rest. Reflect. Repeat.”
— The Pomodoro Technique × Modern Web Engineering

Pomora was designed to improve consistency and attention through structured work sessions.
It supports task hierarchies, daily stats, smart timers, and personalized modes — all powered by
Django REST API (Backend) and Vue 3 + Vite (Frontend).

⚡ Stack Summary

🧠 Distinctiveness & Complexity

Pomora stands out as a fully decoupled full-stack web application —
built with a clean separation between the frontend and backend layers,
ensuring scalability, maintainability, and production-readiness.

🔹 Architectural Overview

Layer	Technology	Description
Backend (API Server)	🐍 Django REST Framework	Handles authentication, CRUD logic, statistics, and token-based authorization (JWT).
Frontend (Client App)	🧩 Vue 3 + Vite	Provides a reactive and modular SPA interface with dynamic state management using Pinia.
Database	🐘 PostgreSQL	Stores users, projects, tasks, subtasks, and productivity stats with relational integrity.
Cache Layer	🔥 Redis	Improves timer and session performance by caching user state and data temporarily.
Deployment	☁️ Dockerized Stack	Production-ready containerized environment for CI/CD and scalability.

⚙️ Why It’s Unique

Unlike most CS50W projects which keep Django in an MVC setup,
Pomora separates responsibilities using a REST API architecture and an independent frontend framework (Vue 3).

This structure allowed:

Full token-based authentication using djangorestframework-simplejwt
Dynamic real-time timer synchronization via cached user sessions
Component-based architecture for reusability and clean UI design
A stateful productivity experience where backend logic and frontend visuals stay decoupled but in sync

💡 Technical Highlights

JWT Authentication with refresh/access token rotation
Custom User Model extending AbstractUser with focus & mode settings
Nested Serializers to handle complex relations (Projects → Tasks → Subtasks)
Automated Tests for APIs, models, and serializers
Pagination & Filtering for optimized query performance
Responsive Design built with Vue + Tailwind for mobile-first UX
CI/CD Integration using GitHub Actions for automated testing and deployment

In essence, Pomora bridges psychology-backed productivity with modern software engineering.
A project that is both technically rich and purpose-driven.

🧩 File Structure & Implementation Details

Pomora follows a clean modular architecture, separating frontend, backend, and core logic.
Each layer is self-contained, with clear boundaries and consistent naming conventions.

📂 Project Tree Overview

Pomora/
│
├── api/                     # Django REST Framework (backend)
│   ├── models.py            # Core models: User, Project, Task, Subtask, Mode, Stats
│   ├── serializers.py       # DRF serializers with nested relations
│   ├── views.py             # ViewSets + APIViews for CRUD logic
│   ├── urls.py              # API endpoints
│   ├── test_api.py          # Unit tests for REST endpoints
│   ├── test_models.py       # Tests for models and relationships
│   └── utils_api.py         # Helper functions (Auth, validation)
│
├── client/                  # Vue 3 + Vite (frontend)
│   ├── src/
│   │   ├── components/      # Reusable UI components (Timer, Tasks, Modals)
│   │   ├── stores/          # Pinia state stores (Auth, Tasks, Timer)
│   │   ├── views/           # Page views (Home, Stats, Projects)
│   │   ├── router/          # Route definitions
│   │   ├── assets/          # Global styles & icons
│   │   └── main.ts          # Vue app entry point
│   ├── index.html           # App mount point
│   └── vite.config.ts       # Build & alias configuration
│
├── main/                    # Django project root
│   ├── settings.py          # Environment configs, DRF, JWT, PostgreSQL setup
│   └── urls.py              # Root routing
│
├── requirements.txt         # Python dependencies
├── package.json             # Frontend dependencies & scripts
├── .env                     # Environment variables for both client/server
└── README.md                # This documentation

⚙️ Backend — Django REST Framework

Models:
- Project, Task, Subtask, Tag, Mode, Stats
- Extended User model for personalization (e.g., focus modes)
Serializers:
- Nested serialization for complex relational data
- Custom depth logic for task–subtask hierarchy
Authentication:
- JWT-based via djangorestframework-simplejwt
- Token refresh flow for secure session management
Testing:
- Model integrity + API endpoint verification using pytest and django.test.Client

🎨 Frontend — Vue 3 + Vite + TypeScript

State Management:
- Pinia stores for auth, tasks, alerts, timer
- Persistent timer state across navigation
Routing:
- Lazy-loaded views using Vue Router for performance
Styling:
- TailwindCSS utility classes with dark mode support
- Smooth UI transitions with Vue’s built-in <transition> & <teleport>
Build:
- Vite for blazing-fast hot reloads and optimized production bundles

🧠 Example Code Snippet — JWT Auth (Backend)

class TagViewSet(viewsets.ModelViewSet):
    """Tag CRUD with user-level filtering"""
    queryset = Tag.objects.all()
    serializer_class = TagSerializer
    permission_classes = [permissions.IsAuthenticated]

    def get_queryset(self):
        return self.queryset.filter(user=self.request.user)

💻 Example Code Snippet — Pinia Store (Frontend)

export const useTimerStore = defineStore("timer", {
  state: () => ({
    currentTimer: "pomo",
    timeLeft: 1500,
    running: false,
  }),
  actions: {
    startTimer() {
      this.running = true;
      setInterval(() => this.timeLeft--, 1000);
    },
    stopTimer() {
      this.running = false;
    },
  },
});

The architecture emphasizes clarity, modularity, and scalability — perfectly aligning with modern web engineering standards.

🚀 Core Features & Functionality

Pomora brings together productivity, focus, and modern web engineering —
blending psychology-backed time management with scalable software design.

⏱ Pomodoro Timer

Smart 25-minute focus sessions with short & long breaks
Fully configurable durations per user-defined Modes
Auto-start options for seamless transitions between focus and break sessions
Real-time countdown synced with backend session states

🧩 Task & Project Management

Create, edit, and organize Projects, Tasks, and Subtasks
Assign color-coded Tags for quick categorization
Track estimated vs. completed Pomodoro sessions per task
Nested relationships between Projects → Tasks → Subtasks

Project
 ├── Task
 │    ├── Subtask A
 │    └── Subtask B
 └── Task (Independent)

💡 Custom Modes & Personalization

Define up to 3 custom Pomodoro modes (e.g. “Deep Work”, “Study Sprint”)
Adjustable timer settings for each mode (focus, short/long breaks)
Automatically syncs with backend user profile

{
  "mode": "Deep Work",
  "pomo": 40,
  "short_break": 7,
  "long_break": 20
}

📊 Productivity Stats & Charts

Interactive charts built with ApexCharts
Track daily & weekly focus metrics
Data synced via REST API for long-term productivity insights
Beautiful visual reports for each user’s performance trend

🔐 Authentication & Security

JWT Authentication (Access + Refresh tokens)
Secure token storage and automatic renewal
Password hashing and user model extension with settings
Authenticated API endpoints protected via DRF permissions

🧠 Additional Functionalities

Feature	Description
🗂 Pagination	Efficient navigation for large lists of tasks/projects
🧩 Reusable Components	Modular and composable Vue components
📱 Responsive Design	Optimized for desktop, tablet, and mobile
🌙 Dark Mode UI	Built-in styling for night-friendly productivity
🧪 Testing Suite	Backend tests for models, APIs, and serializers

“Productivity isn’t about doing more — it’s about focusing better.” Pomora embodies that principle, blending efficiency and elegance in every detail.

⚙️ Setup & Installation

Ready to explore Pomora?
Follow these simple steps to run the project locally — both backend (Django) and frontend (Vue 3).

🐍 Backend — Django REST API

# 1️⃣ Clone the repository
git clone https://github.com/PeakPy/Pomora.git
cd Pomora

# 2️⃣ Create and activate a virtual environment
python -m venv env
source env/bin/activate   # (On Windows: env\Scripts\activate)

# 3️⃣ Install dependencies
pip install -r requirements.txt

# 4️⃣ Set up environment variables
cp .env.example .env
# Edit .env with your own PostgreSQL / Redis credentials

# 5️⃣ Run migrations
python manage.py makemigrations
python manage.py migrate

# 6️⃣ Start the API server
python manage.py runserver

✅ The backend will now be available at: http://127.0.0.1:8000/

🧩 Frontend — Vue 3 + Vite

# 1️⃣ Move into the client folder
cd client

# 2️⃣ Install dependencies
npm install

# 3️⃣ Start the development server
npm run dev

💻 The frontend will run on: http://localhost:5173/ (or your configured Vite port)

🧠 Environment Variables Example (`.env`)

# Backend
DEBUG=True
SECRET_KEY=your_secret_key_here
ALLOWED_HOSTS=127.0.0.1,localhost

# Database
DB_NAME=pomora
DB_USER=postgres
DB_PASSWORD=1234
DB_HOST=localhost
DB_PORT=5432

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
ACCESS_TOKEN_LIFETIME=604800  # 1 week
REFRESH_TOKEN_LIFETIME=2592000  # 1 month

🧪 Run Tests

# Run Django tests
python manage.py test api

# Optional: Run frontend type check
npm run type-check

🧡 Tip: Use Docker for production deployment — The stack is fully compatible with containerization and CI/CD setups.

🏆 Achievements & Learnings

“Every line of code written in this project is a lesson in clarity, focus, and perseverance.”
— Ehsan Akbari (PeakPy)

🎓 Harvard CS50W Milestone

✅ Course Completed: CS50’s Web Programming with Python and JavaScript
📅 Completion Year: 2021
📜 Official Certificate: certificate.jpg

💡 Key Learnings

🧩 Area	💬 Description
Full-Stack Architecture	Designed a decoupled system with Django REST API and Vue 3 frontend.
API Design	Implemented authentication, pagination, and nested serialization using DRF.
Frontend Engineering	Mastered reactive UI design, reusable components, and state management (Pinia).
Database & ORM	Used PostgreSQL and Django ORM for relational data integrity.
Testing & CI/CD	Built unit tests and integrated GitHub Actions for automated deployment.
Clean Code & Scalability	Followed modular structure and naming conventions for maintainability.

🚀 Personal Growth

Learned to manage complex, multi-layered projects independently.
Strengthened problem-solving and debugging skills under real-world constraints.
Gained deep understanding of RESTful principles and frontend–backend collaboration.
Developed a passion for creating tools that enhance productivity and focus.

🌍 Future Vision

Pomora was more than a project — it was the start of a mindset.
In future iterations, I plan to integrate:

Real-time collaboration features

Cloud sync with Redis Streams

Progressive Web App (PWA) capabilities

AI-driven productivity insights

🙌 Acknowledgments

Special thanks to David J. Malan and the CS50 team
for designing one of the most transformative learning experiences in computer science education.

Name		Name	Last commit message	Last commit date
Latest commit History 622 Commits
.github/workflows		.github/workflows
api		api
client		client
main		main
.gitignore		.gitignore
CS50w-Certificate.jpg		CS50w-Certificate.jpg
LICENSE		LICENSE
Pomora.png		Pomora.png
README.fa.md		README.fa.md
README.md		README.md
manage.py		manage.py
requirements.txt		requirements.txt

License

PeakPy/Pomora

Folders and files

Latest commit

History

Repository files navigation