DEV Community: Nguyễn Công Thuận Huy

From 2800-Line Monolith to Modular FastAPI — Refactoring an AI Geolocation Tool

Nguyễn Công Thuận Huy — Fri, 24 Jul 2026 08:28:55 +0000

From 2800-Line Monolith to Modular FastAPI — Refactoring an AI Geolocation Tool

Netryx Nova is a complete modular rewrite of Netryx Astra V2, an open-source image geolocation system that finds GPS coordinates from a single photo using MegaLoc (CVPR 2025) + MASt3R (ECCV 2024).

The original worked — but it was a 2800-line Tkinter monolith. Here's how we broke it into clean modules, added a web UI, cloud GPU support, and 3 execution engines.

The Problem

The original test_super.py was 2794 lines of inline Tkinter GUI + pipeline logic + indexing + file I/O. Making any change meant scrolling through a massive file, guessing which section to touch, and hoping nothing else broke. There was no separation of concerns, no async, no tests.

Symptoms:

Single file with everything mixed together
Tkinter desktop GUI only (no remote access)
Blocking operations freeze the UI
No test coverage
No engine abstraction (GPU-only, no fallback)

The Architecture

Before (Monolith)

test_super.py (2794 lines)
├── GUI (Tkinter widgets, event handlers)
├── Pipeline (retrieval → matching → consensus)
├── Index builder (PCA fitting, FAISS build)
├── Model loading (MegaLoc, MASt3R)
├── File I/O (.netryx bundles)
└── Community Hub (Hugging Face upload/download)

After (Modular)

app.py                  # FastAPI entrypoint
├── core/               # Business logic
│   ├── pipeline.py     # Async pipeline controller
│   ├── retrieval.py    # FAISS vector search
│   ├── matching.py     # MASt3R dense matcher
│   └── consensus.py    # Grid clustering (pure NumPy)
├── engines/            # Backend abstraction
│   ├── base.py         # EngineBase ABC
│   ├── local_gpu.py    # CUDA/MPS
│   ├── local_cpu.py    # CPU fallback
│   └── cloud_modal.py  # Modal.com T4 GPU
├── ui/                 # Web frontend
│   ├── web_app.py      # FastAPI router (7 endpoints + WS)
│   ├── templates/      # Jinja2 HTML
│   └── static/         # JS (Leaflet, WebSocket) + CSS
├── utils/              # Helpers
│   ├── tile_downloader.py
│   ├── geo_utils.py
│   └── netryx_loader.py
├── modal_app/          # Cloud deployment
│   └── mast3r_worker.py
└── tests/              # 23 pytest tests

Key Decisions

1. EngineBase — Abstract Backend

Instead of hardcoding GPU inference, we defined an abstract EngineBase class with run_stage2(). Three implementations:

LocalGPUEngine — CUDA/MPS, loads models at startup
LocalCPUEngine — same pipeline, runs on CPU
CloudModalEngine — HTTP client to a Modal.com T4 worker

Auto-detection chain: GPU → Cloud → CPU. If you have no GPU but Modal is configured, it uses the cloud transparently.

class EngineBase(ABC):
    @abstractmethod
    def run_stage2(
        self, query_img, candidates,
        progress_callback=None, cancel_event=None, ...
    ) -> dict: ...

2. Async Job Model

The original blocked the UI for minutes during Stage 2. The modular version uses:

POST /search returns 202 Accepted with a job_id
The client connects via WebSocket at /ws/{job_id}
PipelineController runs the job on a background thread, streaming progress through an asyncio.Queue
Each engine slot (default 2) processes candidates in parallel

# Post search → get job_id, then stream results via WS
ws = new WebSocket(`/ws/${jobId}`);
ws.onmessage = (e) => {
    const msg = JSON.parse(e.data);
    if (msg.type === "progress") updateProgress(msg.current, msg.total);
    if (msg.type === "result") showMap(msg.result);
};

3. Spatial Consensus with NumPy

The original had a fragile inline consensus loop. We rewrote it as pure NumPy:

def cluster_matches(matches, cell_size_deg=0.00045):
    grid = np.floor(np.column_stack([lats, lons]) / cell_size_deg).astype(int)
    unique_cells, counts = np.unique(grid, axis=0, return_counts=True)
    # Score each cell: sqrt(inliers) summed per grid cell
    # Winner = densest cluster, not highest single score

This eliminated an entire class of false positives from repetitive architecture.

4. On-the-Fly FAISS

Instead of pre-built index files, we load a .netryx bundle on startup and build a FAISS index in memory:

class FAISSRetrieval:
    def __init__(self, bundle_path):
        data = load_netryx_bundle(bundle_path)
        self.index = faiss.IndexFlatIP(1024)
        self.index.add(normalize(data.descriptors))
        self.metadata = data.metadata

What Changed vs. Original

Aspect	Original (Astra V2)	Nova
Lines of code	~2800 in one file	~1500 across 20+ files
UI	Tkinter desktop	FastAPI + Leaflet + WebSocket
Engine	GPU-only	GPU / Cloud GPU / CPU
Async	Blocking	202 + WS streaming
Tests	None	23 tests, `ruff` + `mypy` clean
Setup	`pip install -r requirements.txt`	`pyproject.toml` with dev tooling
Consensus	Inline heuristic	NumPy grid clustering
Cloud	None	Modal.com T4 GPU ($30 free credits)

The Cloud GPU Bonus

No GPU? Modal gives $30 free credits on signup — deploy the MASt3R worker on a T4 in one command:

pip install modal
modal setup
modal deploy modal_app/mast3r_worker.py

The engine auto-detects Modal tokens and falls back gracefully.

Results

21/23 tests pass (2 skipped — faiss not installed in CI)
ruff zero warnings, mypy strict mode clean
Response times identical to the monolith (same models, same pipeline)
Repo is publish-ready with .gitignore, .env.example, and updated README

Check It Out

https://github.com/mangodxd/Netryx-Nova

Netryx Nova is a modular fork of Sairaj Balaji's Netryx Astra V2. All geolocation credit goes to the original pipeline.

I kept deploying broken .env files, so I built a tool to catch them

Nguyễn Công Thuận Huy — Thu, 23 Jul 2026 07:45:48 +0000

I kept deploying broken .env files, so I built a tool to catch them

You know the feeling. You push to production, the app crashes, and the logs say:

Error: DATABASE_URL is not defined

You check your .env file. It's there. You check your code. It's there. Turns out you added DATABASE_URL to .env.example but forgot to update the actual .env on the server.

Or worse: you removed a variable from the code but left it in .env, and now you have a mystery secret sitting in production with no idea what it's for.

EnvDoctor is a Rust CLI tool that catches these problems before they reach production.

What it does

ash cargo install envdoctor cd your-project envdoctor scan

`
EnvDoctor Scan Report
????????????????????
Project: .
Scanned: 2026-07-23 07:11:04 UTC
Duration: 0.32s

Summary
???????
Total variables: 47
Defined in .env: 12
Used in code: 84
Warnings: 5

Issues
??????
? DATABASE_URL (warning): Variable 'DATABASE_URL' is used in code but not defined in .env
at src/config.ts:12:21

? OLD_API_KEY (info): Variable 'OLD_API_KEY' is defined in .env but not used in code
at .env:5
`

Four rules out of the box

Rule	What it catches
R001 Missing Definition	Variable used in code but not in any .env file
R002 Unused Variable	Variable defined in .env but never referenced in code
R003 Naming Convention	Variable name doesn't match UPPER_SNAKE_CASE (configurable)
R004 Undocumented Variable	Variable in .env but missing from .env.example

Why not just use dotenv-linter?

dotenv-linter checks .env file syntax and formatting. EnvDoctor does something different: it cross-references your code with your .env files. It knows which variables you actually use and which ones are missing.

It's like the difference between a spell checker and a linter. One checks the document, the other checks if the document makes sense.

Multi-language support

EnvDoctor uses tree-sitter AST parsing (not regex) for accurate detection across 6 languages:

JavaScript/TypeScript - process.env.X, import.meta.env.X
Python - os.environ['X'], os.getenv('X')
Rust - std::env::var("X"), env!("X")
Go - os.Getenv("X"), os.Lookupenv("X")
Ruby - ENV['X'], ENV.fetch('X')

Real-world test

I ran it on Payload CMS - a large TypeScript monorepo:

8,666 files scanned
119 unique variables detected
844 code usages found
123 warnings (all legitimate - variables used in examples/templates but not defined at root level)
Completed in under 1 second

No false positives. No crashes.

Multiple output formats

`ash

Terminal output

envdoctor scan

CI-friendly (exit code 0 or 1)

envdoctor check

HTML report

envdoctor export --format html -o report.html

JSON for tooling

envdoctor export --format json -o report.json

Explain a specific variable

envdoctor explain DATABASE_URL
`

Configuration

Create an envdoctor.toml in your project root:

` oml
[analysis]
naming_pattern = "^[A-Z][A-Z0-9_]*$"
naming_min_length = 2
strict_mode = false

[scan]
exclude = ["node_modules/", "target/", "dist/**"]
`

How it works

Scanner -> Adapter -> IR -> Analysis -> Report | | | | | File Tree- Common 4 rules Text/JSON/HTML discovery sitter graph

Scanner discovers files with glob filtering
Adapters parse each language with tree-sitter (not regex)
IR Builder normalizes everything into a common graph
Analysis Engine runs rules against the graph
Renderer outputs results

Installation

ash cargo install envdoctor

Or build from source:

ash git clone https://github.com/mangodxd/envdoctor cd envdoctor cargo build --release

What's next

CI pipeline integration (GitHub Actions)
More rules (unused imports in .env files, cross-service variable sharing)
TUI for interactive exploration

GitHub: github.com/mangodxd/envdoctor
crates.io: crates.io/crates/envdoctor

Built with Rust. MIT licensed.

I Built a Tool to Generate Developer Portfolios Automatically

Nguyễn Công Thuận Huy — Sat, 18 Apr 2026 13:34:23 +0000

Writing a developer portfolio is honestly painful.

You have to:

describe your projects
format everything nicely
keep it updated

So I built a tool that does it for you.

👉 It automatically generates a clean portfolio from your data.

Features:

Generate portfolio in seconds
Clean and minimal design
No setup needed
Easy to customize

Live demo: https://mangodxd.github.io/auto-portfolio-generator/
GitHub repo: https://github.com/mangodxd/auto-portfolio-generator

Here’s a quick preview:

Would love to get your feedback 🙌