DEV Community: Harshwardhan S. Ranvir

Voyage Canvas: I Built a Full-Stack AI Travel Planner for Two College Subjects at Once

Harshwardhan S. Ranvir — Sat, 20 Jun 2026 14:40:36 +0000

Flask + Groq API + Supabase + OpenWeatherMap. Multi-page web app. Solo build. Here's how it works and what I learned.

Travel planning is fragmented. You open five tabs — flights on one, hotels on another, things-to-do on a third, budget calculator somewhere else. By the time you have a rough plan, you've spent two hours and you're not even sure the budget holds.

I wanted one thing: enter a destination, set a budget, get a complete day-by-day plan. No switching tabs. No mental math.

So I built Voyage Canvas.

This was a college project — two subjects, one deadline. I architected it to satisfy both: a full-stack web application for my main project and a cloud computing project requiring SaaS, DBaaS, and PaaS components.

GitHub: github.com/Ranvir2028/Voyage-Canvas

What It Does

Voyage Canvas is an AI-powered travel planner. You give it a destination, travel dates, budget, interests, group type, and accommodation preference. It returns a complete, day-by-day itinerary with morning/afternoon/evening activities, real cost estimates, local tips, weather, and a budget breakdown.

Core features:

AI-generated itineraries (Groq API — Llama 3.3 70B with fallback chain)
Smart budget allocation across accommodation, food, transport, activities
Live weather + 5-day forecast via OpenWeatherMap
Auto local currency detection for 80+ destinations
User accounts with saved itinerary history
Destination explorer with AI-powered search
PDF export and print
Deployed on Render with Supabase PostgreSQL as the database

What it does NOT do:

No real flight/hotel booking (it's a planner, not a booking engine)
No live pricing — cost estimates are AI-generated approximations
Currency rates are hardcoded (not live exchange rates)

Architecture

voyage-canvas/
├── backend/
│   ├── app.py              ← Flask server + all API routes
│   ├── ai_service.py       ← Groq API integration + fallback chain
│   ├── weather_service.py  ← OpenWeatherMap integration
│   ├── budget_service.py   ← Budget allocation logic
│   ├── currency_service.py ← Local currency detection
│   ├── database.py         ← PostgreSQL via Supabase
│   └── settings.py         ← Config + env vars
│
└── frontend/
    ├── pages/              ← 6 HTML pages
    ├── css/                ← 5 stylesheets
    └── js/                 ← 6 JS modules

Stack:

Layer	Technology
Backend	Python 3.12, Flask, Flask-CORS
AI	Groq API (Llama 3.3 70B)
Database	PostgreSQL via Supabase
Weather	OpenWeatherMap API
Auth	Token-based (SHA-256 + secrets)
Deployment	Render (web service) + Supabase (DBaaS)
Frontend	Vanilla HTML/CSS/JS — no framework

Flask serves both the API and the frontend pages from a single server. No React, no Vue — just clean vanilla JS with a modular file structure.

Deep Dive: How Each Component Works

1. AI Itinerary Generation — `ai_service.py`

This is the core of the project. The generate_itinerary() function takes user inputs and builds a structured prompt that tells the model exactly what JSON to return.

The prompt enforces strict rules:

prompt = f"""You are a professional travel planner. Generate a complete {days}-day itinerary for {destination}.

CRITICAL RULES:
1. You MUST generate EXACTLY {days} day objects in the "days" array
2. Return ONLY valid JSON — no markdown, no explanation, no extra text
3. Every field must have a real value — no nulls, no empty strings
4. Budget numbers must be realistic for {currency_sym}{budget} total over {days} days
"""

The response schema is detailed — each day object has morning, afternoon, and evening slots, each with time, title, description, location, cost, and an insider tip. Plus top-level fields for summary, best time to visit, local cuisine, packing list, weather, and budget breakdown.

The fallback chain:

LLMs hit rate limits. Groq's free tier is especially aggressive. So ai_service.py doesn't just call one model — it tries a chain:

FALLBACK_MODELS = [
    "llama-3.3-70b-versatile",   # Primary
    "llama-3.1-8b-instant",      # Fallback 1
    "mixtral-8x7b-32768",        # Fallback 2
    "gemma2-9b-it",              # Fallback 3
]

If the primary model hits a 429, it waits (up to 20 seconds, per the Retry-After header) and tries the next model. This makes the app resilient without requiring a paid API plan.

The day count problem:

AI models don't always return the exact number of days you ask for. A 7-day request might come back with 5 days. The function detects this and fills the gap programmatically:

existing_days = result.get("days", [])
if len(existing_days) < days:
    for i in range(len(existing_days) + 1, days + 1):
        base = existing_days[-1].copy()
        base.update({
            "day": i,
            "date": f"Day {i}",
            "theme": f"Day {i} — Exploration",
            ...
        })
        existing_days.append(base)

Not elegant, but it guarantees the frontend never breaks because an itinerary is missing days.

2. Database — `database.py`

Supabase provides the managed PostgreSQL instance — the schema itself is still mine to define. init_db() runs this on startup:

Three tables: users, sessions, itineraries.

CREATE TABLE IF NOT EXISTS users (
    id           SERIAL PRIMARY KEY,
    username     TEXT UNIQUE NOT NULL,
    email        TEXT UNIQUE NOT NULL,
    password     TEXT NOT NULL,
    full_name    TEXT NOT NULL,
    created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS sessions (
    token      TEXT PRIMARY KEY,
    user_id    INTEGER NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS itineraries (
    id          SERIAL PRIMARY KEY,
    user_id     INTEGER NOT NULL,
    destination TEXT NOT NULL,
    duration    INTEGER NOT NULL,
    budget      REAL NOT NULL,
    data        TEXT NOT NULL,   -- Full JSON blob
    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Auth is token-based. On login, a 64-character hex token is generated with secrets.token_hex(32) and stored in the sessions table. Every protected API request checks this token via the Authorization: Bearer <token> header.

Passwords are SHA-256 hashed with a salt before storage. Not bcrypt — a tradeoff made for a deadline-bound college project, not something I'd ship to production as-is.

Generated itineraries are stored as JSON blobs in the data column. The full AI response goes in as a string, retrieved and parsed on demand. Simple, and it works.

3. Budget Service — `budget_service.py`

The budget allocator splits the total budget across six categories using percentage weights:

pct = {
    "accommodation": 0.35,
    "food":          0.25,
    "transport":     0.15,
    "activities":    0.15,
    "shopping":      0.05,
    "misc":          0.05
}

The weights adjust based on selected interests. Shopping-heavy trips shift 5% from misc to shopping. Adventure/outdoor trips shift 5% from food to activities. The allocation is also broken down per day, so users see both the total and the daily allowance for each category.

4. Currency Service — `currency_service.py`

80+ destinations mapped to their local currencies with hardcoded exchange rates. The function does keyword matching — if "tokyo" or "japan" appears in the destination string, it returns JPY with rate 149.5.

def get_currency(destination: str) -> dict:
    dest = destination.lower().strip()
    for key, currency in CURRENCY_MAP.items():
        if key in dest or dest in key:
            return {**currency, "detected": True}
    return {"code": "USD", "symbol": "$", "name": "US Dollar",
            "rate": 1.0, "detected": False}

The limitation is obvious: exchange rates change and these don't. A live rates API would fix this. I didn't have time to wire one in before the deadline.

5. Flask Backend — `app.py`

Flask serves both the frontend pages and the REST API from a single process. Page routes serve HTML files directly:

@app.route('/planner')
def planner():
    return send_from_directory(PAGES_DIR, 'planner.html')

API routes handle data:

@app.route("/api/generate-itinerary", methods=["POST"])
def generate():
    data = request.get_json()
    result = generate_itinerary(data)
    # Auto-save if user is logged in
    user = get_current_user()
    if user:
        save_itinerary(user_id=user['id'], ...)
    return jsonify({"success": True, "itinerary": result})

Generated itineraries auto-save to the database if the user is logged in. No extra step required.

For deployment, the host is set to 0.0.0.0 — required for Render, which injects the $PORT environment variable dynamically. gunicorn handles production serving.

6. Frontend Architecture

Six pages, no framework. Each page has its own JS module:

main.js — global utilities, API helper, toast notifications, date formatting
auth.js — login, register, logout, auth guard
planner.js — 4-step form with progress indicator
itinerary.js — render the full AI response, budget pie chart, maps iframe
explore.js — destination cards, modal, AI-powered search
dashboard.js — user stats, saved itineraries, profile

The API helper in main.js automatically attaches the auth token to every request:

async function apiCall(endpoint, method = "GET", body = null) {
    const token = localStorage.getItem("vc_token");
    const headers = { "Content-Type": "application/json" };
    if (token) headers["Authorization"] = `Bearer ${token}`;
    ...
}

The design is a dark luxury travel magazine aesthetic — deep navy, gold accents, Cormorant Garamond for display text, Bebas Neue for stamps. CSS variables handle the full design system.

The Planner Flow

Four steps, one page, no reloads:

Step 1 — Destination & Dates: City name, start date, number of days

Step 2 — Budget: Slider with USD/INR toggle. Budget updates in real time. Currency auto-detects based on destination.

Step 3 — Preferences: Interest tags (Culture, Food, Adventure, Nightlife, etc.), group type (Solo/Couple/Family/Friends), accommodation tier (1-star to 5-star, Airbnb)

Step 4 — Summary & Generate: Review all inputs, then hit Generate. The AI call takes 10-20 seconds. A loading overlay with animated text keeps the user informed.

On success, the full itinerary JSON is saved to localStorage and the user is redirected to /itinerary.

Cloud Architecture (How It Satisfied Two Subjects)

This is the part I planned deliberately.

The project had to satisfy a cloud computing subject's requirements for SaaS, DBaaS, and PaaS components alongside the main web project. Instead of building two separate projects, I designed Voyage Canvas to cover both:

SaaS — Voyage Canvas itself. A web application delivered as a service, accessible from any browser
DBaaS — Supabase. Managed PostgreSQL. No server to configure, no backups to manage manually
PaaS — Render. The Flask application deploys from a render.yaml config. Push to GitHub, it deploys
AI as a Service — Groq API. The AI capability is consumed as an external API, not self-hosted

One codebase. Two subjects. One deadline. That's the decision I'm most satisfied with in this project.

Sample Output

Itinerary generation request:

{
  "destination": "Tokyo",
  "days": 5,
  "budget": 800,
  "currency": "USD",
  "interests": ["Culture", "Food", "Shopping"],
  "groupType": "Solo",
  "accommodation": "3-star"
}

What comes back (abbreviated):

{
  "destination": "Tokyo",
  "totalDays": 5,
  "summary": "A 5-day solo journey through Tokyo...",
  "days": [
    {
      "day": 1,
      "theme": "Arrival & First Impressions",
      "morning": {
        "title": "Senso-ji Temple, Asakusa",
        "cost": 0,
        "tips": "Arrive before 8am to avoid crowds"
      },
      ...
    }
  ],
  "budgetBreakdown": {
    "accommodation": 280,
    "food": 200,
    "transport": 120,
    "activities": 120,
    "shopping": 40,
    "misc": 40
  }
}

Voyage Canvas's Home Page Screenshot:

Key Engineering Decisions

Why Flask over Django or FastAPI?

Scope and speed. Flask gave me exactly what I needed — routing, JSON responses, static file serving — without the overhead of learning Django's ORM or FastAPI's async patterns under a deadline. For a project this size, Flask is the right call.

Why no frontend framework?

React or Vue would have added a build step, npm dependency management, and component architecture overhead. The app has six pages and predictable state. Vanilla JS with modular files handled it cleanly. The choice kept the project deployable without a separate frontend build process.

Why Supabase over SQLite?

The cloud computing requirement pushed me toward a managed database. But even without that constraint, SQLite breaks the moment you deploy to a stateless server — Render's filesystem resets on every deploy. Supabase gave me a persistent PostgreSQL instance with a free tier that covers the project's needs.

Why store itineraries as JSON blobs?

The AI response structure is nested and variable — different trip lengths produce different shapes of data. Normalizing it into relational tables would have required 5+ tables and complex joins. Storing the full JSON blob and parsing it on retrieval is simpler, faster to build, and easier to change. The tradeoff is you can't query inside the itinerary data — acceptable for this use case.

Why a fallback model chain?

Groq's free tier has aggressive rate limits. A single model would fail under any real load. The fallback chain — Llama 3.3 70B → Llama 3.1 8B → Mixtral → Gemma — means the app degrades gracefully instead of returning a 429 error to the user. The user might get a slightly less capable model, but they get a response.

What I Learned

1. Prompt engineering is real engineering

Getting the AI to return valid, consistently structured JSON every time took more iteration than any other part of the project. Vague prompts produce vague output. The final prompt is explicit to the point of being verbose — it restates the day count requirement three times, includes an example JSON structure, and lists critical rules as numbered items.

The model still sometimes returns fewer days than requested. Hence the programmatic fallback.

2. Stateless servers break assumptions

First deployment on Render: the app worked locally, failed in production. The issue was localhost vs 0.0.0.0 for the Flask host and SQLite file paths that assumed persistent storage. Switching to 0.0.0.0 and Supabase fixed both. Local development assumptions don't always hold on cloud platforms.

3. Rate limits require architecture decisions, not just error handling

A try-catch around an API call handles the error. A fallback model chain handles the user experience. The difference between the two is the difference between an app that crashes gracefully and one that keeps working.

4. Currency and cost data ages badly

The currency rates in currency_service.py are hardcoded to values from when I built this. They're already stale. For anything meant to run long-term, external rate APIs are not optional — they're infrastructure.

5. Designing for two constraints produces better architecture

Having to satisfy both a web project rubric and a cloud computing rubric forced decisions I wouldn't have made otherwise — Supabase instead of SQLite, Render instead of running it locally, separating services cleanly so each had a clear cloud equivalent. Constraints pushed the architecture toward something more production-realistic.

Limitations

Currency rates are hardcoded — they drift from real rates over time
Password hashing uses SHA-256, not bcrypt — fine for a college project, not for production
No real-time pricing — cost estimates are AI approximations, not scraped data
The Supabase free tier pauses after inactivity — cold start delay on first request
No mobile-responsive CSS — the frontend is desktop-only

Where It Stands

Voyage Canvas is done. It works, it's deployed, and it satisfied both subjects it was built for. I'm not actively extending it — there are other projects ahead of it in the queue.
The codebase is on GitHub. It's a working full-stack app — clone it, set up your own API keys and database, and it runs locally.

Quick Start

git clone https://github.com/Ranvir2028/Voyage-Canvas.git
cd Voyage-Canvas/backend
pip install -r requirements.txt

Create backend/.env:

VISION_KEY=your_groq_api_key
OPENWEATHER_API_KEY=your_openweather_key
DATABASE_URL=your_supabase_connection_string

Run:

python app.py

Open http://localhost:5000.

You'll need a Groq API key (free at console.groq.com) and an OpenWeatherMap key (free tier works). Supabase is optional if you modify database.py to use SQLite for local testing.

GitHub: github.com/Ranvir2028/Voyage-Canvas

Portfolio: harshwardhan-ranvir.vercel.app

LinkedIn: linkedin.com/in/harshwardhan-s-ranvir-20a328378

CERBERUS: I Built a Network Sentinel Because My Router Wasn't Enough

Harshwardhan S. Ranvir — Fri, 12 Jun 2026 10:31:32 +0000

A deep dive into building a Python-based network surveillance tool with Scapy, automatic router detection, and a two-phase watch system.

Most people never think about what's actually on their home network. The router has a device list somewhere behind three login screens and a UI that looks like it was designed in 2009. You check it once, forget about it, and move on.

That's not good enough.

I wanted to know my network — not by logging into the router every time, but through automation. A tool that runs, learns what's supposed to be there, and then tells me when something isn't. So I built CERBERUS.

This post covers what it does, how every component works, the engineering decisions behind it, and what I actually learned building it — including the parts that were genuinely difficult.

What CERBERUS Does

CERBERUS is a Python-based network sentinel. It scans your local network using ARP, learns which devices are trusted, and runs a continuous surveillance loop that alerts you when something unknown shows up.

Feature list:

Automatic router and subnet detection (no manual config)
ARP-based device discovery with wake-up broadcast
Two-phase operation: Learning Mode → Surveillance Mode
Unknown device alerts with CRITICAL log entries
Structured file + console logging (reusable module)
Auto-generated known_devices.json and cerberus.log
Windows Npcap auto-installer
Cross-platform: Linux, macOS, Windows

What it does NOT do (...yet):

No port scanning (that's CERBERUS v2)
Won't detect devices that block ARP responses entirely
No persistent background daemon — runs in terminal
No push/email alerts, just logged output

Architecture: Four Modules, One Purpose

cerberus/
├── cerberus_scan.py        # Main orchestrator
├── cerberus_logger.py      # Reusable logging setup
├── router_detector.py      # Network auto-configuration
├── npcap_installer.py      # Windows Npcap helper
├── known_devices.json      # Auto-generated trusted list
└── cerberus.log            # Auto-generated activity log

The design is intentionally modular. Each file has one job. cerberus_scan.py orchestrates everything but doesn't do the heavy lifting itself — it delegates to the other modules and handles the main execution flow.

The two auto-generated files (known_devices.json and cerberus.log) are created at runtime. You don't set them up. CERBERUS creates them when it first runs.

Security note: known_devices.json stores MAC addresses of your trusted devices.

Deep Dive: How Each Component Works

1. Router Detection — `router_detector.py`

Before scanning anything, CERBERUS needs to know what network to scan. This is where most tools either require manual configuration or make a dumb assumption. CERBERUS tries to be smarter.

The RouterDetector class uses Python's netifaces library to query the system's default gateway:

gateways = netifaces.gateways()
gateway_ip, interface = gateways['default'][netifaces.AF_INET][:2]

Once it has the interface, it fetches the actual subnet mask:

addrs = netifaces.ifaddresses(interface)
netmask = addrs[netifaces.AF_INET][0]['netmask']
cidr = sum(bin(int(x)).count('1') for x in netmask.split('.'))
network_address = f"{network_addr}/{cidr}"

This gives you the correct CIDR notation — say, 192.168.1.0/24 or 10.0.0.0/22 — based on your actual network, not a guess.

The fallback: If subnet mask detection fails (some systems don't return this reliably), CERBERUS falls back to a /24 assumption:

network_base = '.'.join(router_ip.split('.')[:-1]) + '.0/24'
TARGET_NETWORK = network_base
logger.warning(f"Using default /24 network assumption: {TARGET_NETWORK}")

This covers the vast majority of home networks. If your network is different, you'll see the warning and can hardcode TARGET_NETWORK in the config section of cerberus_scan.py. It's a practical trade-off — automatic detection works 95% of the time, and the fallback handles the rest without crashing.

2. ARP Scanning — The Core of CERBERUS

ARP (Address Resolution Protocol) is how devices on a network map IP addresses to MAC addresses. It's stateless, has no authentication, and every device on your network responds to it. That makes it ideal for discovery.

CERBERUS builds a broadcast ARP request using Scapy:

arp_request = ARP(pdst=TARGET_NETWORK)
ether_frame = Ether(dst="ff:ff:ff:ff:ff:ff")
packet = ether_frame / arp_request

answered_list = srp(packet, timeout=3, verbose=0)[0]

clients = []
for sent, received in answered_list:
    clients.append({"ip": received.psrc, "mac": received.hwsrc})

ARP(pdst=TARGET_NETWORK) creates an ARP request asking "who has every IP in this range?"

Ether(dst="ff:ff:ff:ff:ff:ff") wraps it in an Ethernet broadcast frame — every device on the network receives this.

srp() (send/receive at Layer 2) sends the packet and listens for responses. Whatever responds gets added to the clients list with their IP and MAC.

The wake-up call:

Before the ARP scan, CERBERUS sends a broadcast ICMP ping:

broadcast_ip = '.'.join(TARGET_NETWORK.split('/')[0].split('.')[:3]) + '.255'
send(IP(dst=broadcast_ip)/ICMP(), verbose=0)
time.sleep(1)

Some devices go into a low-power state and take a moment to respond to ARP. The broadcast ping nudges them awake before the scan. It doesn't work on every device — anything that ignores pings or blocks ICMP stays invisible — but it improves discovery rates on typical home networks.

3. Learning Mode vs Surveillance Mode

This two-phase design is the core logic of CERBERUS.

Phase 1 — Learning Mode (first run only):

def learn_network_mode():
    current_devices = scan_network()
    known_macs = [device["mac"] for device in current_devices]
    save_known_devices(known_macs)
    return known_macs

On first run, there's no known_devices.json. CERBERUS detects this, scans the network, saves every discovered MAC as trusted, and creates the file. No alerts. Everything found in learning mode is considered legitimate.

Phase 2 — Surveillance Mode (every run after):

def surveillance_mode(known_macs):
    while True:
        current_devices = scan_network()

        for device in current_devices:
            if device["mac"] not in known_macs:
                logger.warning(f"Unknown: {device['ip']} - {device['mac']}")

        if unknown_devices:
            logger.critical(f"ALERT: {len(unknown_devices)} intruder(s) detected!")

        time.sleep(SCAN_INTERVAL)

Every 60 seconds (configurable), CERBERUS scans, loads the trusted MAC list, and compares. Any MAC not in the trusted list triggers a WARNING. If unknown devices are found, CRITICAL level alerts fire for each one.

The loop runs until Ctrl+C. No scan limit. CERBERUS watches until you tell it to stop.

Why MAC addresses and not IPs?

IP addresses change. Devices get new IPs via DHCP on every reconnect. MAC addresses are hardware identifiers — they're stable. Tracking by MAC means a device can reconnect on a different IP and CERBERUS still recognizes it.

4. The Logging Module — `cerberus_logger.py`

def setup_logging(log_file="cerberus.log", level="INFO", silent_mode=False):
    formatter = logging.Formatter(
        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        datefmt="%Y-%m-%d %H-%M-%S"
    )

    # Always writes to file
    file_handler = logging.FileHandler(log_file, mode="a", encoding="utf-8")

    # Console output optional
    if not silent_mode:
        console_handler = logging.StreamHandler(sys.stdout)

I built this as a separate module for a reason: I'll use it in future projects. Same interface, drop it in, configure the log file name and level. No rewriting.

Key behaviors:

Always appends to file — you don't lose previous scan history
Console output is optional via silent_mode=True
Five log levels available: DEBUG, INFO, WARNING, ERROR, CRITICAL
Millisecond-precision timestamps on every entry

CERBERUS uses WARNING for unknown devices and CRITICAL for confirmed intruder alerts. The distinction matters when parsing logs programmatically.

5. Windows Npcap Auto-Installer — `npcap_installer.py`

Windows doesn't give raw socket access out of the box. Scapy needs Npcap (a packet capture driver) to function on Windows. Without it, nothing works.

Most tools say "install Npcap manually" and leave you to figure it out. I didn't want that. The auto-installer handles it:

Check if already installed — registry lookup + file system check + live Scapy test
If not found — offer options: auto-install, manual install, or skip
Auto-install path — downloads installer, runs silent install with these flags:

/S                    # Silent mode, no GUI
winpcap_mode=yes      # WinPcap API compatibility
loopback_support=yes  # Capture localhost traffic
admin_only=no         # Allow non-admin capture

The version is currently hardcoded to Npcap 1.79. It'll work fine for the foreseeable future — Npcap doesn't have breaking releases frequently — but it's something to revisit in v2.

This module ended up being more code than the scanner itself. Building it taught me more about Windows internals than I expected: registry access with winreg, process management with subprocess, installer flags, and the gap between "it works on my machine" and "it works on someone else's machine."

Sample Output

Learning Mode (first run):

==================================================
PROJECT CERBERUS: The Network Sentinel
==================================================
✔️ Network detected: 192.168.1.0/24
Router: 192.168.1.1
Your IP: 192.168.1.x
Interface: wlan0
--------------------------------------------------
No known devices file found. Starting learning mode...
Scanning 192.168.1.0/24...
Found 5 devices.
Learned 5 devices. They are now trusted.

Surveillance Mode — clean scan:

------------------------- Scan 1 -------------------------
Scanning 192.168.1.0/24...
Found 5 devices.
All devices are trusted.

Surveillance Mode — intruder detected:

------------------------- Scan 4 -------------------------
Scanning 192.168.1.0/24...
Found 6 devices.
WARNING  - Unknown: 192.168.1.108 - xx:xx:xx:xx:xx:xx
CRITICAL - ALERT: 1 intruder(s) device detected!
CRITICAL - INTRUDER: 192.168.1.108 - xx:xx:xx:xx:xx:xx

For security reasons i'm not putting the original terminal outputs here.

Key Engineering Decisions

Why Scapy over subprocess + system arp?

The alternative was calling arp -a via subprocess and parsing text output. That breaks when output format changes across OS versions (and it does). Scapy gives you structured data directly, cross-platform control, and fine-grained timeout/retry configuration. The learning curve is steeper, but you're not writing a brittle text parser.

Why JSON for device storage?

No database overhead for a list of MAC addresses that'll never exceed 50 entries on a home network. JSON is human-readable, directly editable, and parseable without any dependencies. If you want to add a device manually or remove one, open the file and edit it. Simple.

Why 60-second scan intervals?

30 seconds felt aggressive for passive home network monitoring — unnecessary traffic and CPU overhead. 120 seconds means an intruder goes unnoticed for two minutes. 60 is the balance. It's also directly configurable: change SCAN_INTERVAL in cerberus_scan.py.

Why separate the logging module?

Reusability. cerberus_logger.py has no CERBERUS-specific logic. It's a clean logging setup function. I'll drop it into the next project without touching it.

What I Actually Learned

1. Scapy's documentation is scattered

Most tutorials cover sending a single ping. Understanding srp() (Layer 2 send/receive) versus sr() (Layer 3) took actual time — reading source code, not just docs. There's no single good resource that covers it end-to-end. You have to piece it together.

2. ARP is stateless. That's the attack surface.

Building this made the theory real. ARP has no authentication. Any device can respond to any ARP request, including one it didn't ask for — that's how ARP spoofing works. I understood this conceptually before. After building CERBERUS, I understood it practically.

3. Device discovery is harder than it looks

Not all devices respond to ARP every time. Sleeping devices, aggressively firewalled devices, some IoT hardware — they don't always reply. The wake-up broadcast ping helps, but it's not a complete solution. This is the core limitation that's driving CERBERUS v2: multiple discovery methods, not just ARP.

4. Windows is a different world for networking

Linux gives you raw socket access with sudo. Windows gates it behind a kernel driver (Npcap). Building the auto-installer taught me about Windows registry interaction, silent installer flags, and the difference between making a tool that works on your development machine versus one that someone else can actually run.

5. AI helped with syntax. Debugging was still mine.

I used AI assistance for Scapy syntax and parts of the Npcap implementation. But when something failed — wrong subnet detection, missed devices, logging output inconsistencies — figuring out why required reading logs, testing across configurations, and sometimes reading library source code. AI accelerates. It doesn't replace the diagnostic work.

Limitations and CERBERUS v2

What v1 doesn't solve:

Devices that don't respond to ARP stay invisible
No port/service fingerprinting — you see a device, not what it's running
No persistent daemon — closes when terminal closes
No alerting beyond log output (no email, no webhook, no SMS)
Npcap version hardcoded on Windows

What CERBERUS v2 is adding:

Docker containerization — runs anywhere, including Raspberry Pi
Nmap integration for port scanning and service detection
Multiple discovery methods (not just ARP)
SQLite for persistent device history
REST API for status queries
Webhook/email notifications
Smarter intruder classification

v2 is in active development.

Quick Start

Prerequisites:

Python 3.7+
Linux/macOS: run with sudo (raw packet access requires root)
Windows: run as Administrator (auto-installer handles Npcap)

git clone https://github.com/Ranvir2028/Cerberus-The-Network-Sentinel.git
cd Cerberus-The-Network-Sentinel
pip install -r requirements.txt

Run:

# Linux/macOS
sudo python3 cerberus_scan.py

# Windows (Administrator terminal)
python cerberus_scan.py

First run enters learning mode automatically. Every run after that is surveillance.

Dependencies (from requirements.txt):

scapy==2.6.1
netifaces-plus==0.12.5
requests==2.32.5
colorama==0.4.6

Security Note

Only use CERBERUS on networks you own or have explicit permission to monitor. ARP scanning sends packets to every IP in your network range. On a network you don't own, that's unauthorized network activity.

What's Next

CERBERUS v2 is being built now. The goal is a containerized network sentinel that runs continuously on a home server or Raspberry Pi, scans with multiple discovery methods, and notifies you without you having to watch a terminal.

The v1 code is on GitHub named Cerberus: The Network Sentinel. Read it, break it, use it to understand ARP scanning.

GitHub: github.com/Ranvir2028/Cerberus-The-Network-Sentinel

Portfolio: harshwardhan-ranvir.vercel.app

LinkedIn: linkedin.com/in/harshwardhan-s-ranvir-20a328378

DEV Community: Harshwardhan S. Ranvir

Voyage Canvas: I Built a Full-Stack AI Travel Planner for Two College Subjects at Once

What It Does

Architecture

Deep Dive: How Each Component Works

1. AI Itinerary Generation — ai_service.py

2. Database — database.py

3. Budget Service — budget_service.py

4. Currency Service — currency_service.py

5. Flask Backend — app.py

6. Frontend Architecture

The Planner Flow

Cloud Architecture (How It Satisfied Two Subjects)

Sample Output

Key Engineering Decisions

What I Learned

Limitations

Where It Stands

Quick Start

CERBERUS: I Built a Network Sentinel Because My Router Wasn't Enough

What CERBERUS Does

Architecture: Four Modules, One Purpose

Deep Dive: How Each Component Works

1. Router Detection — router_detector.py

2. ARP Scanning — The Core of CERBERUS

3. Learning Mode vs Surveillance Mode

4. The Logging Module — cerberus_logger.py

5. Windows Npcap Auto-Installer — npcap_installer.py

Sample Output

Key Engineering Decisions

What I Actually Learned

Limitations and CERBERUS v2

Quick Start

Security Note

What's Next

1. AI Itinerary Generation — `ai_service.py`

2. Database — `database.py`

3. Budget Service — `budget_service.py`

4. Currency Service — `currency_service.py`

5. Flask Backend — `app.py`

1. Router Detection — `router_detector.py`

4. The Logging Module — `cerberus_logger.py`

5. Windows Npcap Auto-Installer — `npcap_installer.py`