home pag

BR@NCH

Inspiration

BR@NCH was born from a structural idea: exploration should feel cumulative. In games, skill trees visually represent growth — each action unlocks new branches. That visual logic is powerful because it makes progress tangible. We wanted to apply that same graph-based progression to real-world movement.

Instead of treating the map as a search engine, BR@NCH treats it as a living structure. You begin at a root location and physically expand outward. Every visited place becomes a node in a growing graph. The result is not just navigation — it is visible, personal expansion through space.

This structure feels novel because your movement generates geometry. The map evolves based on where you go. It is not a static interface; it is a personal branching artifact of your life.

What it does

BR@NCH is a real-time, graph-driven exploration platform that turns neighborhoods into expanding trees.

Rooted starting point: Each user begins with a root waypoint — home or any meaningful location. This becomes the trunk of their exploration graph.
Visit with intention: Mark a location as visited and immediately reflect through a guided journal prompt. Exploration is paired with mindfulness.
Automatic spatial branching: Upon visiting, the system queries nearby points of interest and attaches them as child nodes. New physical movement unlocks new graph depth.
Graph-first visualization: Locations render on a live Leaflet map and are visually distinct by category. Unvisited nodes subtly animate to suggest opportunity.
Hierarchical navigation panel: A sidebar renders the nested waypoint tree, allowing structured traversal of your spatial history.
Immutable journaling: Each user-location pair stores a single persistent reflection. Revisits surface prior thoughts, reinforcing memory and growth.

The system transforms passive movement into intentional discovery. Exploration becomes structured, visible, and reflective.

How we built it

Tech Stack

Layer	Technology	Rationale
Backend	Python 3.10+, Flask 3.0, SQLAlchemy 2.0	Lightweight, explicit architecture with strong typing.
Database	SQLite (dev), MySQL-ready	Simple development workflow with production scalability.
Frontend	React 18, TypeScript, Vite	Deterministic state management and type safety.
Styling	Tailwind CSS	Rapid iteration and consistent theming.
Maps & Geo	Leaflet, CartoDB tiles, Photon (OSM), Nominatim	Open, reliable geospatial tooling.
Code Quality	Black, isort, mypy, pytest	Enforced correctness and maintainability.

Architecture

Backend:

Request-scoped sessions ensure safe ORM lifecycle handling.
Waypoints stored in flat format with JSON children references for flexible tree reconstruction.
Journal entries constrained per (user, waypoint) pair for deterministic behavior.
External POI querying handled with retry logic and failure tolerance.

Frontend:

Centralized API orchestration logic isolates side effects.
Predictive prefetching reduces perceived latency.
Stable references prevent race conditions in async flows.
Animations handled in CSS to preserve rendering performance.

Data Models

Model	Key Fields	Notes
User	id, username, lat, lon, root_waypoint_id	Indexed for efficient spatial lookup.
Waypoint	id, api_id, lat, lon, name, children, visited, visited_at	Tree reconstructed dynamically.
JournalEntry	id, user_id, waypoint_id, content, created_at	Immutable per user/location pair.

Key Implementation Details

Accurate Haversine distance calculations for geospatial correctness.
Indexed latitude/longitude for fast bounding-box queries.
Deduplication against existing API IDs to prevent redundant nodes.
ISO timestamp serialization for consistent frontend parsing.
Graceful fallback handling for incomplete external POI metadata.

Challenges we ran into

1. External POI Reliability

Free open-source POI services introduced rate limits and inconsistent availability. Mitigations:

Migrated to Photon for improved stability.
Implemented exponential backoff retry logic.
Reduced redundant calls through client-side caching.
Designed system to degrade gracefully if discovery fails.

2. Scaling the Graph

As trees deepened, rendering and loading became more expensive. Mitigations:

Predictive prefetching of likely next nodes.
Local caching keyed by parent ID.
Lazy rendering of non-visible nodes.
Ensured all optimizations were additive — not required for correctness.

Accomplishments that we're proud of

Graph-native interaction model: The core mechanic — real-world branching — is structurally distinct from traditional mapping tools.
Meaningful exploration: Users do not simply collect locations; they reflect on them. Journaling ties movement to memory.
Community potential: By anchoring users to geographic roots, the system naturally supports neighborhood discovery and social connection.
Performance-aware engineering: Spatial indexing, caching, and async orchestration maintain responsiveness even as trees grow.
Type-safe system design: End-to-end type contracts prevent silent failures and integration drift.
Intentional UI: Visual pulsing, structured hierarchy, and clean map rendering reinforce the graph metaphor.

What we learned

Software Architecture

Clear separation between data layer and orchestration logic simplifies reasoning.
Contract-first API design enables parallel frontend/backend development.
Predictive optimization must not compromise deterministic behavior.

Geospatial Systems

Accurate distance metrics matter even at neighborhood scale.
External geo services require defensive parsing and timeout handling.
Indexing lat/lon columns yields significant performance gains without specialized extensions.