Lock Genius 🔐🛡️

A secure and modern password manager built with Next.js.

📌 Table of Contents

• Lock Genius 🔐🛡️
  • 📌 Table of Contents
  • 🗣 Introduction
  • ✨ Features
  • 🛠 Tech Stack
  • 🖥 Installation
  • 🚨 License

🗣 Introduction

Lock Genius is a simple yet powerful password manager you need. Built with modern web technologies and security best practices.

✨ Features

• Social Login with GitHub
• Secure Password Generation
  • Cryptographically secure random generation
  • Customizable password options (length, character sets)
  • Copy to clipboard functionality
• Guest mode — generate and store up to 50 passwords locally without signing in
• Cloud sync — passwords sync to the database when you log in
• Password Vault Management (view, copy, and delete saved passwords)
• Dark / Light theme toggle
• Health Check API
• Unit Testing

🛠 Tech Stack

• Framework: Next.js 15 with App Router
• Database: PostgreSQL with Prisma ORM
• Authentication: Better Auth (GitHub OAuth)
• UI: Tailwind CSS v4, shadcn/ui, Radix UI
• Testing: Jest, React Testing Library
• Type Safety: TypeScript (strict mode)
• Code Quality: Biome (lint + format)
• Forms: React Hook Form + Zod

🖥 Installation

Prerequisites

1. Install nvm (Node Version Manager):

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

2. Install and use the correct Node.js version:

   nvm install
   nvm use

3. Install pnpm:

   npm install -g pnpm

4. Start the PostgreSQL database via Docker:

   pnpm docker:up

Project Setup

1. Clone the repository:

   git clone https://github.com/iguit0/lock-genius.git
   cd lock-genius

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.example .env

   Fill in the values in .env:

   Variable	Description
   DATABASE_URL	PostgreSQL connection string
   BETTER_AUTH_URL	App URL (e.g. http://localhost:3000)
   BETTER_AUTH_SECRET	Random secret, min 32 characters
   AUTH_GITHUB_ID	GitHub OAuth App client ID
   AUTH_GITHUB_SECRET	GitHub OAuth App client secret

   GitHub OAuth: Create an OAuth App at github.com/settings/developers. Set the callback URL to http://localhost:3000/api/auth/callback/github.

4. Set up the database:

   pnpm db:setup

5. Start the development server:

   pnpm dev

Visit http://localhost:3000 to see the application running.

Additional Commands

• Database Management:

  • pnpm db:reset - Reset database (⚠️ Warning: This will delete all data)
  • pnpm db:studio - Open Prisma Studio for database management

• Testing:

  • pnpm test - Run tests
  • pnpm test:watch - Run tests in watch mode
  • pnpm test:coverage - Run tests with coverage report

• Code Quality:

  • pnpm check - Run Biome (lint + format check)
  • pnpm check:fix - Auto-fix all Biome issues
  • pnpm typecheck - Run TypeScript type checking

• Docker:

  • pnpm docker:up - Start Docker services
  • pnpm docker:down - Stop Docker services
  • pnpm docker:logs - View Docker logs

🚨 License

This project is licensed under the MIT License. Refer to the LICENSE file for more information.