# thiefkid/thiefkid-s-project architecture

> Architecture diagram of the GitHub repository thiefkid/thiefkid-s-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiefkid/thiefkid-s-project
- Repository: https://github.com/thiefkid/thiefkid-s-project

## Overview

This repo is a React + Vite single-page trip-planning app centered on a Sydney/Tasmania 2026 itinerary. The main architectural shape is a client-side UI that reads trip data, enriches it with nearby/location/weather information, and lets users edit or vote on itinerary items.

1. **Entry and app shell**
   - `src/main.jsx` boots the app into `index.html`.
   - `src/App.jsx` is the top-level composition point.
   - The app uses a shared layout with `Header` and `TabNav`, suggesting a tabbed navigation model rather than full page routing.

2. **Primary feature boundaries**
   - The UI is split into domain views under `src/components/`:
     - `itinerary/` for the trip schedule and editing
     - `map/` for geographic visualization
     - `nearby/` for points of interest around locations
     - `packing/` for packing checklists
     - `vote/` for voting/selection
   - These are mostly feature-isolated presentation layers with shared data coming from hooks.

3. **Trip data as the core domain model**
   - `src/data/tripData.js` appears to hold the canonical trip structure or normalized static data.
   - `src/hooks/useTripData.js` is likely the main read-side abstraction for loading trip data into components.
   - The presence of spreadsheets (`itinerary.xlsx`, `Sydney + Tasmania 2026_v2.xlsx`, etc.) indicates the trip dataset originates outside the app and was likely imported/curated from Excel.

4. **Data mutation and persistence**
   - `src/hooks/useTripMutations.js` encapsulates write operations for itinerary changes, such as adding/editing activities.
   - `src/components/itinerary/AddEditActivityModal.jsx` is the primary user-facing editor.
   - This suggests a separation between read models in the view and mutation logic in hooks, keeping components thin.

5. **Local persistence and client state**
   - `src/hooks/useLocalStorage.js` indicates some state is persisted locally in the browser, likely for preferences, votes, or offline-friendly changes.
   - This is an important boundary: some app state is local-only, while other data is shared/synced through Firebase.

6. **Firebase backend integration**
   - `src/firebase.js` is the integration point for Firebase services.
   - `src/scripts/seedFirestore.js` and `src/scripts/seedV2.js` show that Firestore is used as a backend datastore and can be populated from scripts.
   - The architecture therefore includes an external cloud datastore for shared trip state, probably separate from the static trip definition.

7. **Votes and collaborative behavior**
   - `src/hooks/useVotes.js` and `src/components/vote/VoteView.jsx` indicate a voting subsystem.
   - This is likely a shared decision-making feature layered on top of Firestore or local storage, depending on whether votes are collaborative or personal.
   - In a diagram, this is a distinct read/write path from itinerary viewing.

8. **Map and location enrichment**
   - `src/components/map/MapView.jsx` and `LocationPopup.jsx` provide geographic context for itinerary locations.
   - `src/hooks/useNearby.js` likely computes or fetches nearby places relative to a selected destination.
   - `src/test/MapNavigation.test.jsx`, `MapView.test.jsx`, and `LocationNavigation.test.jsx` suggest navigation between itinerary items and map locations is a meaningful interaction path.

9. **Weather as an external data source**
   - `src/hooks/useWeather.js` indicates the app fetches weather data as a side enrichment service.
   - This is likely an external API dependency, separate from the core itinerary datastore and used to display planning context.

10. **Itinerary rendering structure**
    - `src/components/itinerary/ItineraryView.jsx` composes domain subcomponents like `DayCard`, `ActivityItem`, `FlightSegment`, and `HotelCard`.
    - This implies the itinerary is rendered as a structured timeline with different item types, not just a flat list.
    - The modal editor and the day/activity cards form the main interaction surface for itinerary management.

11. **Packing and planning support**
    - `src/components/packing/PackingView.jsx` and `PackingCategory.jsx` form a checklist-style subsystem.
    - This is a separate planning domain, likely backed by local state or shared trip metadata rather than the itinerary timeline itself.

12. **Styling, manifest, and PWA-like packaging**
    - `src/styles/index.css` contains the global styles.
    - `public/manifest.json` suggests the app may be installable or intended to behave like a lightweight mobile-friendly web app.
    - The `BottomBarSafeArea` test name implies mobile-safe-area layout concerns are part of the UI architecture.

13. **Testing and quality boundaries**
    - Tests are concentrated in `src/test/` and cover layout, navigation, map behavior, modal editing, and data consistency.
    - This indicates the app has meaningful interaction and rendering logic worth validating at the component boundary level.

14. **Build and deployment**
    - `package.json`, `vite.config.js`, and `package-lock.json` define the frontend build toolchain.
    - `.github/workflows/deploy.yml` shows CI/CD deployment is automated, so the repo likely builds a static frontend and deploys it to a hosting target.

15. **Overall data flow**
    - The highest-level flow is: curated trip data and Firestore-backed state feed into hooks, hooks feed feature views, views render itinerary/map/packing/voting UI, and user actions flow back through mutation hooks to local storage or Firestore.
    - External enrichment flows in separately for nearby places and weather.

If you are drawing an architecture diagram, the clearest boundaries are: **UI shell**, **feature views**, **data/hooks layer**, **Firebase persistence**, and **external enrichment services** (weather/nearby/location data), with **Excel/seed scripts** as the content-ingestion path into the trip dataset.

Main entry points: [`src/App.jsx`](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/App.jsx) (App), [`src/components/itinerary/ItineraryView.jsx`](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/ItineraryView.jsx) (ItineraryView), [`src/hooks/useTripData.js`](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useTripData.js) (useTripData), [`src/components/map/MapView.jsx`](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/map/MapView.jsx) (MapView)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shell["App shell"]
  node_node_main(("main.jsx<br/>entry<br/>[main.jsx]"))
  node_node_app["App<br/>composition<br/>[App.jsx]"]
  node_node_header["Header<br/>layout<br/>[Header.jsx]"]
  node_node_tabnav["TabNav<br/>navigation<br/>[TabNav.jsx]"]
  node_node_styles["Global styles<br/>styling<br/>[index.css]"]
end

subgraph group_group_itinerary["Trip planner"]
  node_node_itinerary_view["ItineraryView<br/>feature view<br/>[ItineraryView.jsx]"]
  node_node_daycard["DayCard<br/>itinerary item<br/>[DayCard.jsx]"]
  node_node_activity["ActivityItem<br/>itinerary item<br/>[ActivityItem.jsx]"]
  node_node_flight["FlightSegment<br/>itinerary item<br/>[FlightSegment.jsx]"]
  node_node_hotel["HotelCard<br/>itinerary item<br/>[HotelCard.jsx]"]
  node_node_editor["Edit modal<br/>editor"]
end

subgraph group_group_location["Location intel"]
  node_node_mapview["MapView<br/>map view<br/>[MapView.jsx]"]
  node_node_popup["LocationPopup<br/>map ui<br/>[LocationPopup.jsx]"]
  node_node_nearby_view["NearbyView<br/>enrichment view<br/>[NearbyView.jsx]"]
  node_node_weather["useWeather<br/>weather hook<br/>[useWeather.js]"]
end

subgraph group_group_planning["Planning tools"]
  node_node_packing["PackingView<br/>packing view<br/>[PackingView.jsx]"]
  node_node_packcat["PackingCategory<br/>packing ui"]
  node_node_vote_view["VoteView<br/>decision view<br/>[VoteView.jsx]"]
  node_node_votes["useVotes<br/>vote hook<br/>[useVotes.js]"]
end

subgraph group_group_data["Data and backend"]
  node_node_tripdata["tripData<br/>trip model<br/>[tripData.js]"]
  node_node_tripdata_hook["useTripData<br/>read hook<br/>[useTripData.js]"]
  node_node_mutations["useTripMutations<br/>write hook"]
  node_node_localstorage["useLocalStorage<br/>state hook<br/>[useLocalStorage.js]"]
  node_node_firebase["firebase<br/>backend<br/>[firebase.js]"]
  node_node_seed_fs["seedFirestore<br/>seed script<br/>[seedFirestore.js]"]
  node_node_seed_v2["seedV2<br/>seed script<br/>[seedV2.js]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"uses"| node_node_header
node_node_app -->|"uses"| node_node_tabnav
node_node_app -->|"shows"| node_node_itinerary_view
node_node_app -->|"shows"| node_node_mapview
node_node_app -->|"shows"| node_node_nearby_view
node_node_app -->|"shows"| node_node_packing
node_node_app -->|"shows"| node_node_vote_view
node_node_app -->|"styles"| node_node_styles
node_node_itinerary_view -->|"renders"| node_node_daycard
node_node_itinerary_view -->|"renders"| node_node_activity
node_node_itinerary_view -->|"renders"| node_node_flight
node_node_itinerary_view -->|"renders"| node_node_hotel
node_node_itinerary_view -->|"edits"| node_node_editor
node_node_itinerary_view -->|"reads"| node_node_tripdata_hook
node_node_editor -->|"writes"| node_node_mutations
node_node_mapview -->|"shows"| node_node_popup
node_node_mapview -->|"reads"| node_node_tripdata_hook
node_node_mapview -->|"enriches"| node_node_weather
node_node_nearby_view -->|"reads"| node_node_tripdata_hook
node_node_nearby_view -->|"enriches"| node_node_weather
node_node_packing -->|"renders"| node_node_packcat
node_node_vote_view -->|"reads/writes"| node_node_votes
node_node_tripdata_hook -->|"loads"| node_node_tripdata
node_node_tripdata_hook -->|"persists"| node_node_localstorage
node_node_mutations -->|"syncs"| node_node_firebase
node_node_mutations -->|"caches"| node_node_localstorage
node_node_votes -->|"syncs"| node_node_firebase
node_node_votes -->|"caches"| node_node_localstorage
node_node_seed_fs -->|"seeds"| node_node_firebase
node_node_seed_v2 -->|"seeds"| node_node_firebase

click node_node_main "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/main.jsx"
click node_node_app "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/App.jsx"
click node_node_header "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/layout/Header.jsx"
click node_node_tabnav "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/layout/TabNav.jsx"
click node_node_styles "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/styles/index.css"
click node_node_itinerary_view "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/ItineraryView.jsx"
click node_node_daycard "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/DayCard.jsx"
click node_node_activity "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/ActivityItem.jsx"
click node_node_flight "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/FlightSegment.jsx"
click node_node_hotel "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/HotelCard.jsx"
click node_node_editor "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/AddEditActivityModal.jsx"
click node_node_mapview "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/map/MapView.jsx"
click node_node_popup "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/map/LocationPopup.jsx"
click node_node_nearby_view "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/nearby/NearbyView.jsx"
click node_node_weather "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useWeather.js"
click node_node_packing "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/packing/PackingView.jsx"
click node_node_packcat "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/packing/PackingCategory.jsx"
click node_node_vote_view "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/vote/VoteView.jsx"
click node_node_votes "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useVotes.js"
click node_node_tripdata "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/data/tripData.js"
click node_node_tripdata_hook "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useTripData.js"
click node_node_mutations "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useTripMutations.js"
click node_node_localstorage "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useLocalStorage.js"
click node_node_firebase "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/firebase.js"
click node_node_seed_fs "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/scripts/seedFirestore.js"
click node_node_seed_v2 "https://github.com/thiefkid/thiefkid-s-project/blob/master/src/scripts/seedV2.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_app,node_node_header,node_node_tabnav,node_node_styles toneBlue
class node_node_itinerary_view,node_node_daycard,node_node_activity,node_node_flight,node_node_hotel,node_node_editor toneAmber
class node_node_mapview,node_node_popup,node_node_nearby_view,node_node_weather toneMint
class node_node_packing,node_node_packcat,node_node_vote_view,node_node_votes toneRose
class node_node_tripdata,node_node_tripdata_hook,node_node_mutations,node_node_localstorage,node_node_firebase,node_node_seed_fs,node_node_seed_v2 toneIndigo
```

## Components

### App shell

Entry point, shared layout, and global styling.

- [main.jsx](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/main.jsx): entry · Bootstraps the React app into the page. · `src/main.jsx`
- [App](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/App.jsx): composition · Top-level app composition and feature wiring. · `src/App.jsx`
- [Header](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/layout/Header.jsx): layout · Shared top chrome for the app. · `src/components/layout/Header.jsx`
- [TabNav](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/layout/TabNav.jsx): navigation · Tabbed navigation between major views. · `src/components/layout/TabNav.jsx`
- [Global styles](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/styles/index.css): styling · Application-wide styling and layout rules. · `src/styles/index.css`

### Trip planner

Core itinerary browsing and editing experience.

- [ItineraryView](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/ItineraryView.jsx): feature view · Composes the itinerary timeline and item cards. · `src/components/itinerary/ItineraryView.jsx`
- [DayCard](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/DayCard.jsx): itinerary item · Groups activities by day. · `src/components/itinerary/DayCard.jsx`
- [ActivityItem](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/ActivityItem.jsx): itinerary item · Renders a single scheduled activity. · `src/components/itinerary/ActivityItem.jsx`
- [FlightSegment](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/FlightSegment.jsx): itinerary item · Specialized itinerary block for flights. · `src/components/itinerary/FlightSegment.jsx`
- [HotelCard](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/HotelCard.jsx): itinerary item · Specialized itinerary block for accommodations. · `src/components/itinerary/HotelCard.jsx`
- [Edit modal](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/itinerary/AddEditActivityModal.jsx): editor · Add/edit activity form for itinerary changes. · `src/components/itinerary/AddEditActivityModal.jsx`

### Location intel

Map, nearby places, and weather enrichment.

- [MapView](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/map/MapView.jsx): map view · Geographic view of trip locations and navigation. · `src/components/map/MapView.jsx`
- [LocationPopup](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/map/LocationPopup.jsx): map ui · Popup/details for a selected location. · `src/components/map/LocationPopup.jsx`
- [NearbyView](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/nearby/NearbyView.jsx): enrichment view · Shows points of interest near a selected place. · `src/components/nearby/NearbyView.jsx`
- [useWeather](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useWeather.js): weather hook · Fetches weather context for planning. · `src/hooks/useWeather.js`

### Planning tools

Packing and voting subsystems.

- [PackingView](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/packing/PackingView.jsx): packing view · Packing checklist and trip prep UI. · `src/components/packing/PackingView.jsx`
- [PackingCategory](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/packing/PackingCategory.jsx): packing ui · Checklist grouping for packing items. · `src/components/packing/PackingCategory.jsx`
- [VoteView](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/components/vote/VoteView.jsx): decision view · Voting and selection interface. · `src/components/vote/VoteView.jsx`
- [useVotes](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useVotes.js): vote hook · Vote state and persistence logic. · `src/hooks/useVotes.js`

### Data and backend

Canonical trip data, hooks, persistence, and seed scripts.

- [tripData](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/data/tripData.js): trip model · Canonical trip dataset and normalized itinerary content. · `src/data/tripData.js`
- [useTripData](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useTripData.js): read hook · Primary read-side access to trip data. · `src/hooks/useTripData.js`
- [useTripMutations](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useTripMutations.js): write hook · Encapsulates itinerary edits and updates. · `src/hooks/useTripMutations.js`
- [useLocalStorage](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/hooks/useLocalStorage.js): state hook · Browser persistence for local-only app state. · `src/hooks/useLocalStorage.js`
- [firebase](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/firebase.js): backend · Firebase service integration point. · `src/firebase.js`
- [seedFirestore](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/scripts/seedFirestore.js): seed script · Populates Firestore from trip content. · `src/scripts/seedFirestore.js`
- [seedV2](https://github.com/thiefkid/thiefkid-s-project/blob/master/src/scripts/seedV2.js): seed script · Alternate seeding path for trip data. · `src/scripts/seedV2.js`

## Connections

- main.jsx → App: boots · React entry renders the top-level app.
- App → Header: uses · App composes shared header chrome.
- App → TabNav: uses · App provides tabbed navigation.
- App → ItineraryView: shows · Primary itinerary experience is a main tab.
- App → MapView: shows · Map is a primary tab.
- App → NearbyView: shows · Nearby places view is a primary tab.
- App → PackingView: shows · Packing checklist is a primary tab.
- App → VoteView: shows · Voting is a primary tab.
- App → Global styles: styles · Global stylesheet supports the shell and views.
- ItineraryView → DayCard: renders · Itinerary is organized by day.
- ItineraryView → ActivityItem: renders · Day cards contain individual activities.
- ItineraryView → FlightSegment: renders · Special itinerary blocks handle flights.
- ItineraryView → HotelCard: renders · Special itinerary blocks handle hotels.
- ItineraryView → Edit modal: edits · Users add and modify itinerary items through a modal editor.
- ItineraryView → useTripData: reads · View consumes trip data through the read hook.
- Edit modal → useTripMutations: writes · Editor submits itinerary changes through mutation logic.
- MapView → LocationPopup: shows · Map selections open a location popup.
- MapView → useTripData: reads · Map consumes trip locations and itinerary context.
- MapView → useWeather: enriches · Map/planning context can include weather.
- NearbyView → useTripData: reads · Nearby suggestions are anchored to trip locations.
- NearbyView → useWeather: enriches · Nearby/location context can be augmented with weather.
- PackingView → PackingCategory: renders · Packing view organizes items into categories.
- VoteView → useVotes: reads/writes · Vote UI is backed by vote state and persistence.
- useTripData → tripData: loads · Hook provides access to canonical trip data.
- useTripData → useLocalStorage: persists · Trip-facing state may be cached locally.
- useTripMutations → firebase: syncs · Mutations can write to shared backend state.
- useTripMutations → useLocalStorage: caches · Mutations may also update local browser state.
- useVotes → firebase: syncs · Collaborative votes can be stored remotely.
- useVotes → useLocalStorage: caches · Votes or preferences may be kept locally.
- seedFirestore → firebase: seeds · Firestore population path for the app's trip data.
- seedV2 → firebase: seeds · Alternative seeding path for backend content.
