Dopamine Lock Web is a full-stack behavioral discipline platform that turns intention into enforced action: pairing structured focus missions with real-time distraction blocking, short-form content control, and long-term progress tracking.

---

Table of Contents

• Overview
• The Problem
• The Solution
• Why Dopamine Lock Is Different
• Core Features
• Product Workflow
• Architecture
• Backend Modules
• Project Structure
• Installation and Local Setup
• Environment Variables
• Database and Prisma
• API Overview
• Testing
• Security
• Current Status
• Future Roadmap
• Contributing
• License
• Author

---

The Dopamine Lock entry experience introduces the platform's discipline-first philosophy.

Overview

Dopamine Lock Web is a full-stack discipline operating system designed to help users reduce digital distractions, complete focus missions, control short-form content consumption, maintain streaks, measure discipline, and connect focused daily work with long-term personal goals.

It combines several disciplines that are normally shipped as separate, disconnected tools:

• Productivity: mission-based focus sessions with defined start and end states
• Digital wellbeing: Reels/Shorts consumption tracking and daily limits
• Behavioral tracking: discipline scoring, streaks, and an identity engine
• Website restriction: a configurable block manager with preset lists and custom rules
• Analytics: weekly and monthly review of focus, consumption, and score trends
• Goal management: long-term goals linked to the missions that advance them

The platform is not a marketing product with speculative claims; every capability described in this document is backed by a working backend module, database model, or frontend page in this repository.

The Problem

Modern attention is engineered against sustained focus:

• Infinite-scroll feeds and short-form video are designed to interrupt intent, not support it.
• Constant context switching between tabs, notifications, and apps erodes deep work capacity.
• Most productivity tools organize tasks but do nothing to enforce the focus required to complete them.
• Accountability is weak: a to-do list does not know when you open a distracting site mid-task.
• Plans are easy to make and hard to execute consistently over weeks and months.

The Solution

Dopamine Lock Web closes the gap between planning and execution by making focus an enforced, tracked, and scored activity rather than a self-reported intention.

Create Mission
      ↓
Configure Focus Rules
      ↓
Start Active Session
      ↓
Block Distractions
      ↓
Track Focus and Consumption
      ↓
Complete Mission
      ↓
Update Streak and Discipline Score
      ↓
Review Analytics
      ↓
Progress Toward Goals

Each stage writes to the same backend, so a single focus session simultaneously updates streaks, discipline score events, session history, and long-term goal progress.

Why Dopamine Lock Is Different

Capability	Task Managers	Pomodoro Timers	Website Blockers	Habit Trackers	Dopamine Lock Web
Mission-based focus sessions	✕	Partial	✕	✕	✅
Website / app blocking	✕	✕	✅	✕	✅
Reels / Shorts consumption limits	✕	✕	✕	✕	✅
Discipline score	✕	✕	✕	Partial	✅
Streak calendar	✕	✕	✕	✅	✅
Identity engine	✕	✕	✕	✕	✅
Weekly / monthly reviews	✕	✕	✕	Partial	✅
Browser-level enforcement	✕	✕	✅	✕	✅ (API ready, client in development)

Dopamine Lock Web does not compete on any single dimension: it combines mission execution, distraction blocking, and consumption discipline into one behavioral system with a single source of truth.

Core Features

Focus and Execution

Missions are the core unit of work. Each mission can define a duration, blocking rules, and a completion condition; an active session enforces those rules until the mission ends or is abandoned, and every session is recorded to history.

• Mission Center: create, configure, and manage focus missions
• Active Mission Sessions: live session state with pause, resume, and completion
• Block Manager: preset and custom website block rules tied to active missions
• Session History: a complete log of past focus sessions and outcomes

Mission Center	Active Mission Session
Block Manager	Session History

Digital Consumption Control

Short-form content (Reels and Shorts) is tracked per platform against configurable daily limits, with a running consumption score and trend history distinct from focus-session metrics.

• Platform-specific consumption logging
• Configurable daily limits per platform
• Daily consumption score
• Consumption trend history

Consumption Control

Discipline and Consistency

Every completed or failed session generates discipline score events, which feed a streak calendar, an achievement system, and an identity engine that reflects a user’s behavioral trajectory over time.

Streak Calendar	Discipline Score
Achievements	Identity Engine

Progress and Reflection

A dashboard aggregation service pulls focus, consumption, streak, and score data into a single overview, with dedicated analytics, goal tracking, and weekly/monthly review pages for deeper reflection.

Dashboard

Analytics	Goals Hub
Weekly Review	Monthly Review

Account and Security

Standard email/password authentication is backed by JWT sessions, bcrypt hashing, a rate-limited password-recovery flow, avatar uploads, and local HTTPS for realistic development.

Login	Registration
Password Recovery	Local HTTPS
Settings	Profile

Browser Extension Integration

A dedicated backend API (/api/extension) already exposes sync state, mission state, effective blocking rules, and consumption state for a companion browser extension, and records block attempts and consumption events reported by it. The frontend includes a Browser Extension page that surfaces this sync status to the user.

• Backend rule synchronization endpoints
• Mission-state and effective-rules lookup for enforcement decisions
• Block-attempt and consumption-event ingestion
• Extension status tracking (ExtensionStatus model)

Browser Extension Sync Status

Status: The extension-facing API and its data model are implemented and covered by a dedicated database migration. The Manifest V3 browser extension client itself is planned future work and is not yet part of this repository: see Current Status.

Product Workflow

Register or Login
        ↓
Create a Mission
        ↓
Choose Duration and Blocking Rules
        ↓
Start the Active Mission
        ↓
Browser Extension Enforces Restrictions
        ↓
Focus and Consumption Events Are Recorded
        ↓
Streak, Discipline Score, Analytics and Identity Update
        ↓
Weekly and Monthly Reviews Summarize Progress

The backend is the single source of truth for mission state, blocking rules, and consumption limits. The browser extension is the enforcement layer at the edge: it reads effective rules from /api/extension and reports block attempts and consumption events back to the same backend.

Architecture

React / Vite Frontend (frontend/)
        ↓  HTTPS / fetch
Express REST API (backend/src/app.js)
        ↓
Controllers → Services (aggregation & business logic)
        ↓
Prisma ORM (backend/prisma/schema.prisma)
        ↓
PostgreSQL

Companion Browser Extension (planned)
        ↕  /api/extension
Mission, Block Manager and Consumption Services

• Frontend: React 19 + Vite single-page app, routed with React Router, communicating with the API over fetch via a shared API client.
• Backend: Express 5 REST API organized into controllers, validation middleware, and services per domain (missions, consumption, discipline score, analytics, etc.).
• Prisma: schema, migrations, and the generated client that mediate all database access.
• PostgreSQL: the single relational data store for users, missions, sessions, blocking, consumption, achievements, goals, and reviews.
• JWT authentication: bearer tokens issued on login/register and required by authMiddleware on protected routes.
• SMTP (Nodemailer): sends password-reset emails via emailService.
• Local file storage: profile avatars are uploaded with Multer and served statically from backend/uploads/avatars.
• Local HTTPS: both Vite and Express can serve over HTTPS using mkcert-generated certificates for a production-like local environment.

Backend Modules

Module	Responsibility
Authentication	Registration, login, JWT issuance, session identity (/api/auth)
Password Reset	Rate-limited forgot/reset password flow with emailed, single-use tokens
User Profile	Profile data and avatar upload (/api/profile)
Missions	Mission creation and lifecycle (/api/missions)
Mission Session	Active session start/pause/complete tracking (/api/mission-session)
Block Manager	Custom and preset website block rules (/api/block-manager)
Session History	Historical record of completed/failed sessions (/api/session-history)
Streak	Daily consistency tracking (/api/streak)
Discipline Score	Score events and snapshots derived from session outcomes (/api/discipline-score)
Consumption Control	Reels/Shorts logging and limits (/api/consumption)
Analytics	Focus, mission, and consumption analytics (/api/analytics)
Goals	Long-term goals linked to missions (/api/goals)
Achievements	Unlockable achievements by category and rarity (/api/achievements)
Identity	Rank and identity progression (/api/identity)
Weekly & Monthly Review	Period-based performance summaries (/api/reviews)
Dashboard Aggregation	Combined overview across all modules (/api/dashboard)
Browser Extension API	Sync, rules, mission state, and event ingestion for the extension (/api/extension)

Project Structure

Dopamine_lock_web/
├── backend/
│   ├── prisma/
│   │   ├── schema.prisma
│   │   ├── seed.js
│   │   └── migrations/
│   ├── src/
│   │   ├── app.js
│   │   ├── config/prisma.js
│   │   ├── controllers/
│   │   ├── middleware/
│   │   ├── routes/
│   │   └── services/
│   ├── __tests__/
│   ├── server.js
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── context/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── routes/ProtectedRoute.jsx
│   └── vite.config.js
├── Docs/
│   └── screenshots/
└── README.md

Installation and Local Setup

Prerequisites

• Node.js and npm
• PostgreSQL (local or remote instance)
• mkcert for trusted local HTTPS certificates
• A Chromium-based browser, for future extension testing

Clone

git clone git@github.com:AayuAmor/Dopamine_lock_web.git
cd Dopamine_lock_web

Backend setup

cd backend
npm install
cp .env.example .env

Edit .env with your PostgreSQL credentials and secrets (see Environment Variables), then:

npm run prisma:migrate     # apply database migrations
npm run prisma:generate    # generate the Prisma client
npm run prisma:seed        # seed achievements (optional but recommended)
npm run dev                # start the backend with nodemon

The backend also exposes npm start for a non-watch run and npm run prisma:studio to browse data with Prisma Studio.

Frontend setup

cd frontend
npm install
npm run dev

Set VITE_API_BASE_URL in frontend/.env (see below); it defaults to https://localhost:5000/api if unset.

HTTPS setup

Both the frontend and backend default to HTTPS (HTTPS_ENABLED=true) and expect certificates at certs/localhost-key.pem and certs/localhost-cert.pem inside each app folder.

mkcert -install
mkdir -p frontend/certs backend/certs
mkcert -key-file frontend/certs/localhost-key.pem -cert-file frontend/certs/localhost-cert.pem localhost 127.0.0.1 ::1
mkcert -key-file backend/certs/localhost-key.pem -cert-file backend/certs/localhost-cert.pem localhost 127.0.0.1 ::1

• Frontend: https://localhost:5173
• Backend: https://localhost:5000

For plain HTTP development, set HTTPS_ENABLED=false in both .env files and use matching http:// origins to avoid mixed-content errors.

Browser extension setup (future)

The extension client itself is not yet part of this repository (see Current Status). Once available, the intended workflow is:

1. Open the Chromium extension manager (chrome://extensions).
2. Enable Developer Mode.
3. Load the extension directory as an unpacked extension.
4. Point the extension at the backend’s /api/extension base URL with an authenticated bearer token.
5. Sync mission state and blocking rules with Dopamine Lock Web.

Environment Variables

Never commit real values for these: only the placeholders below.

Backend (backend/.env)

PORT=5000
CLIENT_ORIGINS=https://localhost:5173,https://127.0.0.1:5173

DB_NAME=DopamineLock_Web
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_HOST=127.0.0.1
DB_PORT=5432
DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/DopamineLock_Web?schema=public

JWT_SECRET=replace-with-a-long-random-secret
JWT_EXPIRES_IN=7d

FRONTEND_URL=https://localhost:5173
HTTPS_ENABLED=true
SSL_KEY_PATH=certs/localhost-key.pem
SSL_CERT_PATH=certs/localhost-cert.pem

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=smtp-user@example.com
SMTP_PASSWORD=smtp-password
EMAIL_FROM=Dopamine Lock <no-reply@dopaminelock.app>

PASSWORD_RESET_EXPIRES_MINUTES=30
PASSWORD_RESET_RATE_LIMIT_WINDOW_MS=900000
PASSWORD_RESET_RATE_LIMIT_MAX=5

Frontend (frontend/.env)

VITE_API_BASE_URL=https://localhost:5000/api
HTTPS_ENABLED=true
SSL_KEY_PATH=certs/localhost-key.pem
SSL_CERT_PATH=certs/localhost-cert.pem

Database and Prisma

PostgreSQL stores all application data; Prisma manages the schema, relationships, and migrations. All user-facing data (missions, sessions, block rules, consumption logs, discipline score events, achievements, goals, identity snapshots, and review data) is scoped to an owning user.

npm run prisma:migrate    # create/apply a migration
npm run prisma:generate   # regenerate the Prisma client
npm run prisma:seed       # seed the achievement catalog
npm run prisma:studio     # inspect data visually

API Overview

All routes are mounted under /api and, except for /api/health, /api/auth/register, and /api/auth/login, require an Authorization: Bearer <token> header.

Base path	Purpose
/api/auth	Register, login, current user, forgot/reset password
/api/profile	Profile data and avatar upload
/api/missions	Mission CRUD and lifecycle
/api/mission-session	Active session control
/api/block-manager	Block rules and preset lists
/api/session-history	Completed/failed session records
/api/streak	Streak calendar data
/api/discipline-score	Score events and snapshots
/api/consumption	Reels/Shorts logs and limits
/api/analytics	Focus, mission, and consumption analytics
/api/goals	Goal creation and mission linkage
/api/achievements	Achievement catalog and unlocks
/api/identity	Identity rank and progression
/api/reviews	Weekly and monthly review data
/api/dashboard	Aggregated dashboard overview
/api/extension	Extension sync, rules, and event ingestion

Testing

The backend uses Jest and Supertest for API-level testing. The current suite (backend/__tests__/authPasswordReset.test.js) covers the password-recovery flow end to end:

• Valid email returns a generic success response and sends a reset email
• Unknown email returns the same generic success response without sending an email (no account enumeration)
• Missing or invalid email is rejected with 400
• Database and email-service failures are handled safely with 500
• Password-reset requests are rate-limited (429 after the configured threshold)
• Valid reset token successfully updates the password
• Invalid or expired reset tokens are rejected

cd backend
npm test

Negative test cases are expected to pass: a 400/401/429 response for invalid input is the correct, verified behavior, not a failure. Test coverage for the remaining modules (missions, block manager, consumption, etc.) is part of the ongoing roadmap.

Security

• bcrypt password hashing for all stored credentials
• JWT-protected routes via authMiddleware, validated against a live user record on every request
• Ownership-scoped resources: all mission, session, and consumption data is scoped to the authenticated user
• Password reset tokens are hashed at rest, single-use, and time-limited (PASSWORD_RESET_EXPIRES_MINUTES)
• Generic password-reset responses prevent account enumeration by email
• Rate limiting on the forgot-password endpoint (passwordResetRateLimit)
• CORS allowlisting via CLIENT_ORIGINS/FRONTEND_URL, rejecting unrecognized origins
• Local HTTPS for both frontend and backend during development
• Environment-based secrets: no credentials are hardcoded in source
• Ignored sensitive paths: .env, certs/, *.pem, and uploaded avatars are excluded from version control

Warning: Never commit .env, SMTP credentials, database credentials, JWT secrets, uploaded avatars, or private certificate keys.

Current Status

Area	Status
Core web application (frontend + backend)	Complete
Mission, consumption, discipline, and identity features	Complete
Browser extension backend API	Complete
Browser extension client (Manifest V3)	Not yet implemented (planned)
Automated test coverage	Ongoing (password reset covered; other modules planned)
Production deployment	Pending

Future Roadmap

• Chromium browser extension client (Manifest V3) built against the existing /api/extension API
• GitHub integration: connect a user’s repositories to their focus activity
• DevGraph integration: visualize sustained development work alongside discipline metrics
• Developer-focused coding missions, with focus-session weighting based on meaningful commit/development activity
• Cross-device synchronization
• AI-assisted focus coaching
• Team and organization accountability dashboards
• Expanded automated test coverage across all backend modules
• Production-grade cloud storage for avatars (e.g., S3/Cloudinary) replacing local disk storage
• Production email and deployment infrastructure

The GitHub/DevGraph vision extends Dopamine Lock beyond time-based discipline: rewarding developers not just for time spent in focus sessions, but for producing meaningful project activity: commits, coding missions, and sustained development work.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. Push the branch
5. Open a pull request

License

This project currently has no open-source license. All rights are reserved unless stated otherwise.

Author

AayuAmor (github.com/AayuAmor)

Built with React, Vite, Express, PostgreSQL, Prisma, and the broader open-source ecosystem these tools depend on.