ARC Duka – African Ruby Community Shop 🛍️

A modern Ruby on Rails e-commerce platform offering official merchandise for the African Ruby Community (ARC), active since 2010 with over 4,000 members across East Africa.

Live Store: https://duka.nairuby.org

---

🌟 Features

Customer Features

• 🛒 Browse products by category (Shirts, Hoodies, Mugs, Accessories, etc.)
• 🎨 Product variants (sizes, colors) with stock tracking
• 🛍️ Real-time shopping cart with instant updates
• 💳 Multiple payment methods (Card, Bank Transfer, Cash on Delivery)
• 📱 Fully responsive mobile-first design
• 🔐 Secure checkout with guest and authenticated options
• 📧 Order confirmation and tracking
• 💱 Multi-currency support (KES, USD, EUR, GBP)

Admin Features

• 🎛️ Beautiful admin panel powered by Avo
• 📊 Stock management dashboard with low stock alerts
• 📦 Product and variant management
• 🛒 Order management and tracking
• 👥 User management with role-based access
• 📈 Sales and inventory metrics

---

🚀 Tech Stack

• Framework: Ruby on Rails 8.1
• Database: PostgreSQL
• Styling: Tailwind CSS 4.0
• JavaScript: Hotwire (Turbo + Stimulus)
• Admin Panel: Avo 3.0
• Authentication: Devise
• Payment Ready: Stripe, Paystack integration points [Tentative]
• Deployment: Kamal 2.0

---

📦 Quick Start

Prerequisites

• Ruby 4.0.0+
• Rails 8.1+
• PostgreSQL 14+
• Node.js 18+
• Yarn or pnpm

Option 1: Local Setup

1. Clone the repository

   git clone https://github.com/nairuby/duka.git
   cd duka

2. Install dependencies

   bundle install
   yarn install  # or npm install

3. Setup database

   rails db:create
   rails db:migrate
   rails db:seed

4. Start the development server

   bin/dev

5. Visit the application

   • Store: http://localhost:3000
   • Admin Panel: http://localhost:3000/avo
   • Admin Login: admin@duka.com / admin123456

Option 2: Dev Container (Recommended)

This project includes a complete Dev Container setup for consistent development environments.

Requirements:

• Docker Desktop
• VS Code with Dev Containers extension

Steps:

1. Clone the repository
2. Open in VS Code
3. Click "Reopen in Container" when prompted
4. Run rails db:setup in the terminal
5. Run bin/dev to start the server

---

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• CONTRIBUTING.md - How to contribute to the project
• docs/ADMIN_PANEL.md - Admin panel guide
• docs/CHECKOUT_SYSTEM.md - Checkout architecture
• docs/PRODUCT_VARIANTS.md - Product & variant management
• docs/LOGIN_UI_FEATURES.md - Authentication UI details
• docs/DEVELOPMENT.md - Development guide (NEW)
• docs/ARCHITECTURE.md - System architecture (NEW)

---

🧪 Testing

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/product_spec.rb

# Run with coverage
COVERAGE=true bundle exec rspec

# Lint Ruby code
bundle exec rubocop

# Auto-fix linting issues
bundle exec rubocop -a

---

🎨 Code Style

This project follows:

• Ruby Style Guide via RuboCop
• Rails Best Practices
• Tailwind CSS for styling
• Stimulus for JavaScript interactions

---

🗂️ Project Structure

duka/
├── app/
│   ├── avo/              # Admin panel resources
│   ├── controllers/      # Request handlers
│   ├── models/           # Business logic
│   ├── services/         # Service objects (CartService, etc.)
│   ├── views/            # Templates
│   └── javascript/       # Stimulus controllers
├── config/               # Configuration
├── db/                   # Database migrations & seeds
├── docs/                 # Documentation
├── spec/                 # Tests
└── public/               # Static assets

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Write tests for new features
   • Follow the code style guide
   • Update documentation as needed
4. Commit your changes

   git commit -m 'Add amazing feature'

5. Push to your fork

   git push origin feature/amazing-feature

6. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

I'd add this immediately after the Rails Credentials section (or as a new subsection within it), since it's part of the payment gateway setup.

---

Payment Callback (Sandbox Testing)

When testing payments locally, Quikk must be able to reach your application's callback endpoint. Since localhost is not publicly accessible, expose your local Rails server using a tunnel such as Cloudflare Tunnel.

For example:

cloudflared tunnel --url http://localhost:3000

This will provide a public URL similar to:

https://wallpaper-plus-get-glass.trycloudflare.com

Configure the following callback URL in your Quikk Sandbox dashboard:

https://wallpaper-plus-get-glass.trycloudflare.com/payments/callback

The callback endpoint used by this application is:

/payments/callback

Note: Every time you start a new temporary Cloudflare Tunnel, the generated URL changes. Update the callback URL in the Quikk Sandbox dashboard accordingly, unless you are using a permanent tunnel or custom domain.

Quikk Sandbox API Keys

Quikk uses separate API credentials for Sandbox and Production.

When setting up the project for development:

1. Create a new Sandbox application in Quikk.
2. Generate fresh Sandbox API keys.
3. Add them to your development Rails credentials.

quikk:
  api_key: your_sandbox_api_key
  api_secret: your_sandbox_api_secret
  shortcode: "174379"

Important: Quikk Sandbox API keys expire relatively quickly. If authentication suddenly begins failing, generate a new set of Sandbox API keys and update your Rails credentials.

For production deployments, use a separate set of Production API keys in config/credentials/production.yml.enc.

---

🔑 Configuration (Rails Credentials)

This project uses Rails encrypted credentials for sensitive configuration (including Quikk API keys), not plain .env secrets.

Edit development credentials

EDITOR="code --wait" rails credentials:edit --environment development

Notes

• Keep config/master.key private and never commit it.
• config/credentials/*.yml.enc files are safe to commit.
• Non-sensitive local settings (if any) can still go in .env.

---

🚢 Deployment

This project uses Kamal 2.0 for deployment:

# Setup deployment
kamal setup

# Deploy
kamal deploy

# Check status
kamal app logs

See deployment documentation for detailed instructions.

---

📊 Key Features Explained

Cart System

• Session-based cart (no login required)
• Real-time updates with Turbo Streams
• Optimistic UI for instant feedback
• Stock validation before checkout

Checkout Flow

1. Add items to cart
2. Enter shipping information
3. Select payment method (Card, Bank Transfer, COD)
4. Confirm order
5. Receive confirmation email

Admin Panel

• Powered by Avo for beautiful UI
• Manage products, variants, and stock
• View and process orders
• User management with admin roles
• Dashboard with key metrics

---

🌍 About the African Ruby Community

ARC Duka supports the African Ruby Community, promoting open source and software craftsmanship in East Africa since 2010. Revenue from this shop helps fund:

• Monthly meetups and workshops
• Community swag and merchandise
• Conference sponsorships
• Educational initiatives

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

🙏 Acknowledgments

• African Ruby Community members
• All contributors to this project
• Open source libraries and tools used

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Community: African Ruby Community
• Email: organisers@rubyconf.africa

---

Made with ❤️ by the African Ruby Community