📒 Contact Book Pro

A modern, beautiful, cross-platform desktop contact management application built with Go (Golang) and Wails, featuring an intuitive GUI, smart ID system, and a Recycle Bin for safe deletion.

📸 Screenshots

Check the screenshot folder folder for some of the pictures of the interface

🎯 About The Project

Contact Book Pro is a production-ready desktop application that demonstrates modern full-stack development practices using Go for the backend and modern web technologies for the frontend, packaged into a native desktop application via Wails.

Built as part of the SIWES (Students Industrial Work Experience Scheme) program, this project showcases enterprise-grade architecture patterns including:

• 🔐 Permanent Database IDs (like JIRA: CB-0001)
• 🔄 Sequential Display Indices (auto-renumbering)
• 🗑️ Soft Delete with Recycle Bin (like Gmail)
• ♻️ Recovery System (restore deleted contacts)
• 🔒 Duplicate Prevention (unique phone & email)
• 🎨 Modern UI (sidebar navigation, toast notifications)

✨ Features

Core CRUD Operations

• ✅ Create — Add contacts with full validation
• ✅ Read — View all contacts in a beautiful table
• ✅ Update — Edit any contact field
• ✅ Delete — Soft delete to Recycle Bin

Advanced Features

• 🔍 Smart Search — Search by name, phone, email, address, or CB-ID
• 🗑️ Recycle Bin — Recover or permanently delete
• 🔥 Empty Bin — Bulk permanent deletion
• 🆔 Cramable IDs — Easy-to-remember format (CB-0001)
• 📍 Display Index — Sequential numbering (#1, #2, #3)
• 🔔 Toast Notifications — Beautiful success/error feedback
• 📅 Timestamps — Track when contacts are added/deleted
• 🔄 Auto-Migration — Backward compatible with old data

Validation & Safety

• ✓ Letter-only validation for names
• ✓ Phone number format check (7-15 digits)
• ✓ Email format validation
• ✓ Required field checks
• ✓ Duplicate phone/email prevention
• ✓ Confirmation dialogs for destructive actions

UI/UX Excellence

• 🎨 Modern dark sidebar with gradient
• 🌈 Color-coded action buttons
• 💫 Smooth transitions and hover effects
• 📱 Responsive layout
• 🔔 Toast notifications
• 👤 Auto-generated user avatars

🛠️ Tech Stack

Backend

• Go (Golang) v1.22+ — Core language
• Wails v2 v2.12.0 — Desktop framework
• JSON — Data persistence

Frontend

• HTML5 — Structure
• CSS3 — Custom styling with gradients
• Vanilla JavaScript — Frontend logic
• Vite — Build tool

Architecture Patterns

• Repository Pattern — Storage layer abstraction
• Soft Delete — Industry-standard data preservation
• Auto-Migration — Backward compatibility
• Persistent ID Counter — Guaranteed unique IDs

📁 Project Structure

ContactBookGUI/ │ ├── 📄 main.go # Wails entry point ├── 📄 app.go # Core business logic & API ├── 📄 go.mod # Go dependencies ├── 📄 go.sum # Dependency checksums ├── 📄 wails.json # Wails configuration ├── 📄 README.md # This file ├── 📄 LICENSE # MIT License ├── 📄 .gitignore # Git ignore rules │ ├── 📁 models/ │ └── contact.go # Contact data structure │ ├── 📁 storage/ │ └── file_storage.go # JSON storage + ID generation │ ├── 📁 validator/ │ └── validator.go # Input validation │ ├── 📁 frontend/ │ ├── index.html # Main HTML │ ├── package.json # NPM dependencies │ └── src/ │ ├── main.js # Frontend logic │ ├── style.css # Styling │ └── assets/ # Static assets │ ├── 📁 data/ # Auto-generated │ ├── contacts.json # Contact database │ └── .id_counter # Persistent ID counter │ ├── 📁 build/ # Build output └── 📁 screenshots/ # README images

🚀 Getting Started

Prerequisites

• Go 1.22+ — Download

• Node.js 16+ — Download

• Wails CLI:

  go install github.com/wailsapp/wails/v2/cmd/wails@latest

Verify Installation

go version # go1.22+ node --version # v16+ wails version # v2.12+

💻 Installation & Setup

1. Clone the Repository

git clone https://github.com/YOUR-USERNAME/ContactBookGUI.git cd ContactBookGUI

2. Install Dependencies

Go dependencies

go mod tidy

Frontend dependencies

cd frontend npm install cd ..

3. Run Development Mode

wails dev

A desktop window will open! 🎉

🏗️ Building for Production

Create a standalone executable:

wails build

Output:

build/bin/ContactBookGUI.exe # Windows build/bin/ContactBookGUI.app # macOS
build/bin/ContactBookGUI # Linux

The single executable file can be distributed without installation!

📖 Usage Guide

Adding a Contact

1. Click ➕ Add Contact in the sidebar
2. Fill in all fields (validated in real-time)
3. Click 💾 Save Contact

Managing Contacts

• 👁 View — See full contact details
• ✏️ Edit — Update any field
• 🗑 Delete — Move to Recycle Bin

Recycle Bin

• Click 🗑️ Recycle Bin in sidebar
• ♻️ Recover — Restore contact (keeps original CB-ID)
• 💥 Forever — Permanently delete
• 🔥 Empty Bin — Delete all at once

Search

• Click 🔍 Search
• Type any keyword (name, phone, email, address, or CB-ID)
• Real-time results with full action buttons

🆔 ID System Explained

Two-Tier ID System

| Type | Example | Behavior | |||-| | Database ID | CB-0001 | 🔒 Permanent, never changes | | Display Index | #1, #2, #3 | 🔄 Sequential, updates dynamically |

Why Two IDs?

Add contacts: CB-0001 (#1), CB-0002 (#2), CB-0003 (#3) Delete CB-0002: CB-0001 (#1), CB-0003 (#2) ← Display renumbers Add new: CB-0001 (#1), CB-0003 (#2), CB-0004 (#3) Recover CB-0002: CB-0001 (#1), CB-0003 (#2), CB-0004 (#3), CB-0002 (#4)

Database IDs are NEVER reused, ensuring data integrity forever (like GitHub Issues).

🧪 Validation Rules

Field	Rules
First/Last Name	Letters only, required
Phone	7-15 digits (allows +, -, spaces)
Email	Valid email format
Address	Cannot be empty
Duplicate Check	Phone & Email must be unique

🎨 Design System

Color Palette

• Primary: #1a1a2e → #16213e (Sidebar gradient)
• Accent: #0f3460 (Active states)
• Success: #dcfce7 / #166534
• Warning: #fef3c7 / #92400e
• Danger: #fee2e2 / #dc2626

🗺️ Roadmap

• Export to CSV/Excel
• Import from CSV/vCard
• Profile pictures
• Contact groups/tags
• Dark/Light theme toggle
• Cloud sync
• Mobile companion app
• Multi-language support
• Keyboard shortcuts
• Backup & restore

🤝 Contributing

Contributions welcome! Please follow these steps:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License — see LICENSE file for details.

👨‍💻 Author

Olufemi Keripe (a.k.a FEMZYK)

• 🎓 SIWES Student at LASU
• 💼 Aspiring Full-Stack Developer
• 🌍 Lagos, Nigeria 🇳🇬
• 📧 femzykenterprises@gmail.com
• 🔗 [LinkedIn](Working on retrieval)
• 🐙 GitHub

🙏 Acknowledgments

• Wails Project — Amazing Go desktop framework
• Go Team — Powerful, elegant language
• SIWES Program — Practical learning opportunity
• My SIWES Team — Collaboration and support

⭐ Show Your Support

If you found this project helpful, please give it a ⭐ on GitHub!

Built with ❤️ in Lagos, Nigeria using Go + Wails

Report Bug · Request Feature · Documentation