trip - Moses Yebei

The Problem

Travel planners need a self-hostable alternative to cloud-based POI mappers and itinerary tools, avoiding subscription costs and data silos while retaining control over maps and collaboration.

What This Does

This repository provides a minimalist map tracker and trip planner. Core capabilities include marking points of interest on interactive maps, organizing multi-day itineraries, and sharing trips with companions. The backend lives in backend/trip/ (Python, FastAPI/Starlette), with API routes split across routers/auth.py, routers/trips.py, routers/places.py, and routers/settings.py. Data is persisted via SQLAlchemy ORM, with Alembic migrations in backend/trip/alembic/versions/. The user-facing UI is under docs/src/pages/index.tsx (React) and docs/src/components/HomepageFeatures/index.tsx, which consumes the API. A separate mcp-server/server.py provides model-context-Protocol integration. Geocoding providers (Google, OSM, Photon) are wired in backend/trip/utils/providers/.

How It Is Wired

Execution starts at backend/trip/main.py, which instantiates the FastAPI app and includes routers. A request flows: HTTP entry → main.py router dispatch (e.g., routers/places.py) → CRUD operations through backend/trip/db/core.py or utility functions like utils/providers/google.py for API calls → SQLAlchemy session → Alembic-managed schema. The widest blast radius is the router layer; adding a new feature typically requires a new router file or extending an existing one, touching models, a new migration, and the frontend component. The MCP server (mcp-server/server.py) hooks into the same data model but operates as a separate service. The React frontend (docs/src/pages/index.tsx) mounts at the root and renders map components, place lists, and trip-planning forms, communicating via REST endpoints under /api/.

How To Use It

Setup: Deploy with Docker Compose: docker-compose up -d (root docker-compose.yml). No code changes are required for a basic run.

Configuration: Set environment variables for OIDC authentication and provider API keys. The configuration docs reference config.py or .env for these values; the README notes “Refer to the configuration documentation… to set up OIDC authentication and other keys.”

Running it: After containers start, the app is available at http://localhost:8080 (port mapping in docker-compose.yml). The first run may require creating an admin user via the OIDC flow or direct DB setup as per docs.

Real-World Use

A small travel agency self-hosts the app to let coordinators map POIs and build day-by-day itineraries. Staff add locations via the UI (leveraging OSM/Photon providers), attach notes or images, and generate shareable trip links for clients. The OIDC config restricts access to agency accounts only. When a trip is finalized, the export feature (docs/docs/trips-planner/trip-export.md) generates a static itinerary PDF or JSON for distribution.

Code Health & Issues

Static analysis found: 364 files total; Python 85 files, TypeScript 68 files; 1 test file (location not specified in the summary); 100 documentation files. CI/CD pipelines exist in .github/workflows/ (Docker publish and GitHub Pages deploy). License file license.txt is present. Lockfiles (package-lock.json, requirements.txt) are present. No structural red flags were detected.

Observed gaps: Only one test file is present, suggesting limited test coverage. The repository is a fork of itskovacs/trip with 0 stars, which may indicate low community activity or a fresh fork.

The Bottom Line

The repo delivers a functional, self-hosted trip-planning stack with a clean Python backend and React UI, packaged for one-command Docker deployment. It’s well-suited for individuals or teams prioritizing data privacy and offline control. The main trade-off is limited testing and a small contributor base; anyone relying on it for critical planning should assess the migration path from the upstream itskovacs/trip project and verify long-term maintenance comfort.

What the analyser found

Deployment readiness

7/7

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

Composition

364 files

Python85
TypeScript68
Markdown37
HTML36
SCSS33
JSON21

ReactAngularDjangoExpressTailwindDocker

Module dependencies

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

graph LR n0_backend_trip_models_models["models"] n1_src_src_app_types_trip["trip"] n2_src_src_app_types_poi["poi"] n3_backend_trip_config["config"] n4_src_app_services_api_service["api.service"] n5_c_app_services_utils_service["utils.service"] n6_backend_trip_utils_utils["utils"] n7_backend_trip_deps["deps"] n8_backend_trip_security["security"] n9_src_src_app_shared_utils["utils"] n3_backend_trip_config --> n8_backend_trip_security n3_backend_trip_config --> n6_backend_trip_utils_utils n7_backend_trip_deps --> n3_backend_trip_config n7_backend_trip_deps --> n0_backend_trip_models_models n7_backend_trip_deps --> n8_backend_trip_security n0_backend_trip_models_models --> n3_backend_trip_config n0_backend_trip_models_models --> n6_backend_trip_utils_utils n8_backend_trip_security --> n3_backend_trip_config n8_backend_trip_security --> n0_backend_trip_models_models n8_backend_trip_security --> n6_backend_trip_utils_utils n6_backend_trip_utils_utils --> n3_backend_trip_config n4_src_app_services_api_service --> n2_src_src_app_types_poi n4_src_app_services_api_service --> n1_src_src_app_types_trip n5_c_app_services_utils_service --> n1_src_src_app_types_trip n5_c_app_services_utils_service --> n4_src_app_services_api_service n9_src_src_app_shared_utils --> n1_src_src_app_types_trip n1_src_src_app_types_trip --> n2_src_src_app_types_poi classDef cyc stroke:#ef4444,stroke-width:2px; class n0_backend_trip_models_models,n3_backend_trip_config,n6_backend_trip_utils_utils,n8_backend_trip_security cyc;

Dependencies

2 of 24 declared dependencies are a major version behind. Resolved 24 of 24 against the registry.

Package	Declared	Latest	Behind
`typescript`	~5.6.2	7.0.2	2 major
`pillow`	~=11.2	12.3.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

Add a test suite; this repository has nonehigh152 occurrences

152 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Replace the wildcard CORS origin with an explicit allow listhigh

backend/trip/main.py

allow_origins=["*"]

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:22, python:3.12-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.

Set persist-credentials: false on checkoutmedium

.github/workflows/gh-pages.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

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.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/docker-publish.yml

2 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.