Barcody

Universal Barcode Intelligence & Scanning Suite

Barcody is a professional, high-performance monorepo designed for scanning, managing, and analyzing barcodes at scale. Built with Next.js 16, NestJS 11, and Tailwind CSS v4, it provides a seamless cross-platform experience with real-time data synchronization and advanced analytics.

✨ Core Features

📱 Cross-Platform Scanning: High-performance mobile application for instant precision scanning.
📊 Advanced Analytics: Real-time insights and data visualization for scanned assets.
🌐 Dual Dashboards: Specialized interfaces for both End Users and Administrators.
🔐 Secure Auth: Seamless integration with Google OAuth 2.0.
📁 Universal Support: Full compatibility with QR codes, UPC, EAN, and more.
🎨 Elite UI: Stunning dark-mode interface built with Tailwind CSS v4 and Shadcn UI.
🔌 Real-time Updates: Socket.io integration for instant data synchronization.
🐳 Docker Ready: Fully containerized architecture for effortless deployment.

📸 Application Preview

🌐 User Web App

The end-user experience optimized for speed and clarity.

Feature	Preview
Modern Landing
Precision Scanning
Activity History

🛡️ Admin Dashboard

Comprehensive management suite for system administrators.

Module	Preview
Overview Console
Control Center
Intelligence Lab
User Governance
Global Audit

🛠️ Technology Stack

Frameworks: Next.js 16, NestJS 11
Frontend: React 19, Tailwind CSS v4, Shadcn UI
Mobile: React Native
Backend: Node.js 22, TypeScript
Database: PostgreSQL, Redis
ORM: TypeORM
Real-time: Socket.io
API Docs: Swagger/OpenAPI
Containerization: Docker
Private Networking: Tailscale

🚀 Installation & Setup

Barcody uses a hybrid setup: Docker for services (Database, Redis, Tailscale Sidecars) and either Docker or local Node.js for the applications.

1. Prerequisites

Ensure you have the following installed:

Node.js 22+
Docker and Docker Compose
Git

2. Clone the Repository

git clone https://github.com/nishan-paul-2022/barcody-barcode-scanner-for-anything
cd barcody-barcode-scanner-for-anything

3. Configuration

Create your environment configuration in both the app-backend and app-web directories:

cp app-backend/.env.example app-backend/.env
cp app-web/.env.example app-web/.env

3.1 ⚙️ App Configuration

Essential settings for the application server.

Backend: Update app-backend/.env with your secrets.
Web App: Update app-web/.env with the API URL.
Hash Secret: Run openssl rand -hex 32 and paste into ANALYTICS_HASH_SECRET in app-backend/.env.

3.2 🌐 Google OAuth

To enable user login, you must set up Google OAuth in the Google Cloud Console.

Authorized Redirect URI: http://localhost:3000/api/auth/callback/google

4. Running the Application

Choose the method that fits your needs:

Option A: Local Development (Recommended)

Runs the apps locally with hot-reloading enabled, connected to the Dockerized database and Tailscale proxies. Best for active coding.

make dev

Option B: Full Docker Environment

Runs the entire application suite in Docker containers.

make up

Option C: Production Build

Optimized production deployment via Docker.

make build

Local access points:

Web App: http://localhost:3000

Admin Dashboard: http://localhost:3001

API Docs: http://localhost:3002/api/docs

🔒 Tailscale Private Network Setup

Barcody uses Tailscale to create a secure, private network (Tailnet) so you can access all services remotely over HTTPS without exposing anything to the public internet. The stack uses a Sidecar Architecture — each service gets its own Tailscale container with a dedicated subdomain and automatic SSL certificate.

Why Tailscale?

Without Tailscale	With Tailscale
Services only accessible on `localhost`	Access from any device, anywhere
No HTTPS in development	Automatic HTTPS via Let's Encrypt
Requires port forwarding / reverse proxy	Zero-config private networking
Backend exposed publicly	Backend stays fully private

Part 1 — Account Creation (Web)

Go to tailscale.com and click "Get Started for Free".
Sign in with Google (or your preferred SSO provider).
Complete onboarding — your account creates a private Tailnet automatically.

Part 2 — Install Tailscale on Ubuntu (Terminal)

Run the official one-line install script on your Linux machine:

curl -fsSL https://tailscale.com/install.sh | sh

Authenticate your machine and join your Tailnet:

sudo tailscale up

A login link will appear in your terminal. Open it in your browser and approve the device. Once done, verify your machine has a Tailscale IP:

tailscale ip -4
# Expected output: 100.x.x.x

Part 3 — Admin Console Configuration (Web)

Log in to the Tailscale Admin Console and configure the following:

3.1 Enable MagicDNS

Settings → DNS → MagicDNS → Enable

This allows devices on your Tailnet to reach each other by hostname (e.g., barcody.your-tailnet.ts.net) instead of raw IP addresses.

3.2 Enable HTTPS Certificates

Settings → DNS → HTTPS Certificates → Enable

This allows Tailscale to issue automatic SSL certificates from Let's Encrypt for your Tailnet hostnames.

3.3 Rename Your Machine (Optional but Recommended)

Go to the Machines tab → Click the ... menu next to your PC → Rename

Give your development machine a clean, short name (e.g., kai). This becomes part of your domain: barcody.kai.ts.net.

3.4 Generate an Auth Key

Settings → Keys → Generate Auth Key

This key allows Docker containers to join your Tailnet automatically (non-interactively).

Setting	Value
Type	Reusable
Pre-authorized	✅ Yes
Expiry	Set to your preference

Copy the generated key — it starts with tskey-auth-....

Part 4 — Set Your Domain in the Project

4.1 Add the Auth Key to the Root `.env`

Open the root .env file and add your Tailscale auth key:

# .env (root of the project)
TS_AUTHKEY=tskey-auth-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

4.2 Update the Serve Config Files

The Tailscale sidecar containers read JSON config files from infra/tailscale/ to know which domain and port to serve. You need to update these with your own Tailnet domain.

Your Tailnet domain follows the pattern: <machine-name>.<tailnet-name>.ts.net

Find your exact domain in the Tailscale Admin Console → click your machine → copy the full MagicDNS name.

Update all three serve config files:

infra/tailscale/app-web.json — Web App (port 3000)

{
  "TCP": { "443": { "HTTPS": true } },
  "Web": {
    "barcody.<your-tailnet>.ts.net:443": {
      "Handlers": {
        "/": { "Proxy": "http://web:3000" }
      }
    }
  },
  "AllowFunnel": {
    "barcody.<your-tailnet>.ts.net:443": false
  }
}

infra/tailscale/app-admin.json — Admin Dashboard (port 3001)

{
  "TCP": { "443": { "HTTPS": true } },
  "Web": {
    "admin-barcody.<your-tailnet>.ts.net:443": {
      "Handlers": {
        "/": { "Proxy": "http://app-admin:3001" }
      }
    }
  },
  "AllowFunnel": {
    "admin-barcody.<your-tailnet>.ts.net:443": false
  }
}

infra/tailscale/app-backend.json — Backend API (port 3002)

{
  "TCP": { "443": { "HTTPS": true } },
  "Web": {
    "api-barcody.<your-tailnet>.ts.net:443": {
      "Handlers": {
        "/": { "Proxy": "http://app-backend:3002" }
      }
    }
  },
  "AllowFunnel": {
    "api-barcody.<your-tailnet>.ts.net:443": false
  }
}

Local dev variants: For make dev mode (apps run locally, not in Docker), use the -local variants in infra/tailscale/ — they proxy to host.docker.internal instead of Docker service names.

4.3 Update the API URL in docker-compose.yml

When the web and admin containers are built, they need to know the Tailscale API URL at build time. Open docker-compose.yml and update the build args:

# docker-compose.yml — web service
args:
  - NEXT_PUBLIC_API_URL=https://api-barcody.<your-tailnet>.ts.net/api/v1

# docker-compose.yml — app-admin service
args:
  - NEXT_PUBLIC_API_URL=https://api-barcody.<your-tailnet>.ts.net/api/v1

Part 5 — Launch & Verify

Start the full stack (including Tailscale sidecars):

make dev     # Local dev with Tailscale proxies
# or
make up      # Full Docker stack

Wait ~2 minutes for the Tailscale containers to register with the network and fetch SSL certificates. Then verify:

# Check that the web sidecar received its SSL certificate
docker logs barcody-barcode-scanner-for-anything-ts-web-1
# Look for: cert("barcody..."): got cert

# Check API sidecar
docker logs barcody-barcode-scanner-for-anything-ts-api-1
# Look for: cert("api-barcody..."): got cert

Your Private HTTPS URLs

Once running, your services are accessible at:

Service	URL
🌐 Web App	`https://barcody.<your-tailnet>.ts.net`
🛡️ Admin Dashboard	`https://admin-barcody.<your-tailnet>.ts.net`
⚙️ Backend API	`https://api-barcody.<your-tailnet>.ts.net/api/v1`
📖 API Docs	`https://api-barcody.<your-tailnet>.ts.net/api/docs`

Part 6 — Mobile & Remote Access

Access all services from your phone or any other device using the Tailscale app.

6.1 Install the Tailscale App

iOS: Search for Tailscale in the App Store and install it.
Android: Search for Tailscale in the Google Play Store and install it.

6.2 Login & Connect

Open the Tailscale app on your phone.
Tap Sign in and use the same account you used to create your Tailnet.
Toggle the VPN switch to ON.

6.3 Rename Your Mobile Device (Recommended)

In the Tailscale Admin Console, rename your phone to something like mobile for easy identification.

6.4 Access the App

Open your browser on mobile and navigate to the full Tailscale URL:

Web App: https://barcody.<your-tailnet>.ts.net
Admin: https://admin-barcody.<your-tailnet>.ts.net

Troubleshooting Tips:

Always use the full HTTPS URL — do not omit the https:// prefix.

If a URL fails to load, toggle Tailscale OFF → ON on your phone to refresh the MagicDNS list.

If you see a "Not Secure" warning, wait ~2 minutes for the sidecar to obtain its SSL certificate, then retry.

Part 7 — Tailscale Funnel (Optional Public Access)

By default, all services are private (Tailnet only). To temporarily expose a service to the public internet, use the Makefile shortcuts:

# Enable public access for all services
make funnel-on

# Disable public access (back to Tailnet only)
make funnel-off

⚠️ Warning: Funnel makes your services publicly accessible on the internet. Only enable this for demos or testing, and always disable it afterward with make funnel-off.

Part 8 — Tailscale Architecture Overview

Your Device (Tailscale ON)
        │
        │  Tailnet (encrypted WireGuard)
        │
┌───────▼─────────────────────────────────────────┐
│                 Docker Stack                    │
│                                                 │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ ts-web   │    │ ts-admin │    │ ts-api   │   │
│  │ sidecar  │    │ sidecar  │    │ sidecar  │   │
│  │ :443 SSL │    │ :443 SSL │    │ :443 SSL │   │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘   │
│       │               │               │         │
│  ┌────▼─────┐    ┌────▼─────┐    ┌────▼───────┐ │
│  │  app-web │    │ app-admin│    │app-backend │ │
│  │  :3000   │    │  :3001   │    │  :3002     │ │
│  └──────────┘    └──────────┘    └────────────┘ │
│                                                 │
│  ┌──────────┐    ┌──────────┐                   │
│  │ postgres │    │  redis   │                   │
│  │  :5432   │    │  :6379   │                   │
│  └──────────┘    └──────────┘                   │
└─────────────────────────────────────────────────┘

Each app is paired with a dedicated Tailscale sidecar container that:

Registers a unique hostname on the Tailnet (e.g., barcody, admin-barcody, api-barcody)
Manages SSL certificate issuance automatically via Let's Encrypt
Acts as a reverse proxy, forwarding HTTPS traffic to the app container on the internal Docker network

🔄 CI/CD & Automated Deployment

Barcody is engineered for continuous reliability. Every update to the codebase undergoes an automated deployment journey:

Continuous Integration: GitHub Actions automatically run quality checks and security audits on every push to the repository.
Automated Builds: Upon merging to the main branch, production-optimized Docker images are automatically built and pushed to the GitHub Container Registry (GHCR).
Seamless Deployment: A secure, automated pipeline triggers the production server to pull the latest images and refresh the services instantly, ensuring zero-downtime-ready updates.
Reliable Persistence: The deployment architecture is designed to handle database migrations and persist critical data safely across automated updates.

This automated pipeline guarantees that the production environment always reflects the latest stable version of the application.

📋 Makefile Reference

Command	Description
`make dev`	Start local development (Apps local + DB & Tailscale in Docker)
`make up`	Start full Docker environment
`make build`	Build and start production containers
`make down`	Stop all containers
`make restart`	Restart all containers
`make refresh`	Deep rebuild (use when dependencies change)
`make logs`	Tail logs from all containers
`make funnel-on`	Enable public internet access via Tailscale Funnel
`make funnel-off`	Disable public access (Tailnet-only mode)

Built with ❤️ by KAI

Name		Name	Last commit message	Last commit date
Latest commit History 632 Commits
.github		.github
.husky		.husky
app-admin		app-admin
app-backend		app-backend
app-web		app-web
assets		assets
envs.example		envs.example
infra/tailscale		infra/tailscale
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Makefile		Makefile
README.md		README.md
audit-ci.json		audit-ci.json
commitlint.config.js		commitlint.config.js
docker-compose.local-proxy.yml		docker-compose.local-proxy.yml
docker-compose.ts.yml		docker-compose.ts.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation