project nomad - Moses Yebei

Abstract

Project N.O.M.A.D, is a self-contained, offline survival computer packed with critical tools, knowledge, and AI to keep you informed and empowered—anytime, anywhere.

The Problem

Users need a portable, offline‑first server that bundles education, reference, and AI tools without relying on continuous internet access. Maintaining such a heterogeneous stack (Docker images, AI models, map data, etc.) is error‑prone and hard to orchestrate on a single device.

What This Does

project‑nomad ships a self‑contained web UI and API that orchestrates the required containers, downloads content packs, and exposes an Ollama‑based chat with RAG via Qdrant. The core server lives in admin/bin/server.ts and is configured through admin/.env.example. UI components under admin/inertia/** (React + Tailwind) render the “Command Center”, while service classes in admin/app/services/ implement the heavy lifting (Docker orchestration, model download, benchmark, etc.).

Key files:

admin/app/services/ollama_service.ts – wraps Ollama client, downloads models, invokes inference.
admin/app/services/docker_service.ts – creates, starts, and monitors the auxiliary containers (Kiwix, Kolibri, Qdrant, etc.).
admin/app/controllers/*_controller.ts – HTTP entry points that call the services.

How It Is Wired

Execution starts at admin/bin/server.ts which boots the AdonisJS server and registers the Inertia app (admin/inertia/app/app.tsx). The request flow for a typical AI chat is:

HTTP request → admin/app/controllers/chats_controller.ts → admin/app/services/chat_service.ts.
chat_service calls admin/app/services/ollama_service.ts → dispatchModelDownload (if model missing) → network call via this.ollama.list (outbound) → model inference (counts as one of the 6 functions that call a model).
The response bubbles back through the controller to the client UI component admin/inertia/components/chat/index.tsx.

The most fan‑in module is admin/inertia/lib/api.ts (62 functions, called from six files). Functions with the widest blast radius include catchInternal (called from 59 places) and status (28 places).

Two circular imports exist between admin/app/models/chat_message.ts and admin/app/models/chat_session.ts; breaking this cycle would reduce build‑time coupling.

Deeply nested UI components (e.g., TierSelectionModal.tsx) reach an indentation depth of 10, making future UI tweaks harder to reason about.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/project-nomad.git
cd project-nomad

# Build the production container
docker build -t project-nomad:latest -f Dockerfile .

# Create a .env from the example and edit as needed
cp admin/.env.example .env   # edit .env for any required keys (e.g., DB path)

# Run the container (exposes port 8080)
docker run -p 8080:8080 --env-file .env project-nomad:latest

The server starts on http://localhost:8080. All UI interactions go through the Inertia React frontend; API calls are handled by the AdonisJS controllers under admin/app/controllers/.

Real‑World Use

A field clinic installs the container on a modest Ubuntu workstation, runs the Docker image, and uses the web UI to:

Pull the latest offline Wikipedia ZIM file (admin/app/services/zim_service.ts).
Start the Kolibri container for educational content.
Chat with the local Ollama model to retrieve medical guidance, with the request flowing through ollama_service → Ollama API → response rendered in ChatMessageBubble.tsx.

Code Health & Issues

High – Pin third‑party GitHub Actions – .github/workflows/* uses @vN tags; replace with commit SHA.
High – Push to default branch – .github/workflows/release.yml pushes directly to main; switch to PR workflow.
Medium – Least‑privilege GITHUB_TOKEN – no permissions block in release.yml.
Medium – Pin Docker base image – Dockerfile uses node:22-slim; pin by digest.
Medium – No dependency‑vulnerability scan – add dependency-review-action or osv-scanner.
Medium – Run container as non‑root – add an unprivileged USER in Dockerfile.
Medium – Test coverage is minimal – only 1 test file for ~233 source files.
Low – Missing job timeouts – add timeout-minutes in build-disk-collector.yml.
Low – No repository convention files – add .editorconfig, .gitattributes, formatter config.

No critical findings were reported by the static analysis.

The Bottom Line

project‑nomad delivers a functional offline server stack with clear separation of UI, API, and service layers, but the codebase suffers from duplicated logic, oversized service files, and a few architectural smells (import cycles, deep nesting). It is suitable for teams willing to invest in refactoring and adding test coverage to stabilize the platform for production deployments.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

307 files

TypeScript158
TSX74
Shell12
Markdown12
JSON10
YAML9

ReactTailwindDocker

Module dependencies

The 10 most depended-upon modules of 210, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_dmin_constants_service_names["service_names"] n1_admin_types_collections["collections"] n2_admin_app_utils_fs["fs"] n3_admin_types_system["system"] n4_admin_constants_broadcast["broadcast"] n5_admin_types_benchmark["benchmark"] n6_admin_types_files["files"] n7_admin_types_services["services"] n8_admin_types_zim["zim"] n9_admin_types_downloads["downloads"] n2_admin_app_utils_fs --> n6_admin_types_files n2_admin_app_utils_fs --> n3_admin_types_system n8_admin_types_zim --> n6_admin_types_files

Dependencies

31 of 82 declared dependencies are a major version behind. Resolved 82 of 82 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^22.15.18	26.2.0	4 major
`@adonisjs/inertia`	^3.1.1	5.0.1	2 major
`@adonisjs/vite`	^4.0.0	6.0.1	2 major
`@vitejs/plugin-react`	^4.6.0	6.0.5	2 major
`maplibre-gl`	^4.7.1	6.4.0	2 major
`typescript`	~5.8.3	7.0.2	2 major
`vite`	^6.4.1	8.2.1	2 major
`@adonisjs/auth`	^9.4.0	10.1.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

docker/login-action@v2, docker/build-push-action@v5, cycjimmy/semantic-release-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release.yml

git push origin main

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/release.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

Dockerfile

node:22-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium

1 test files against 233 source files (ratio 0.004)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/build-disk-collector.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.