TRACE

Go outside. Notice more. Leave a trace.

A local-first physical exploration system and illustrated digital field journal.
Capture small real-world discoveries, build a living personal map, and uncover patterns through local AI.

Discover TRACE  •  The Core Loop  •  Explore the Experience  •  Quick Start  •  System Architecture  •  Reference & Docs  •  Contributing

Most modern digital tools compete fiercely for your screen time. Social algorithms optimize for passive scrolling, fitness apps reduce the outdoors to calorie counts and heart rate zones, and navigation systems rush you along the fastest highway between two points.

TRACE is built on an inverse philosophy:

The world is the interface. The screen should start and end the experience, not become the experience.

When you step out into your neighborhood or wander an unfamiliar street, the physical world is filled with quiet, unnoticed details:

• Wild chamomile blossoming through a curb seam.
• The distinct acoustic rhythm of water echoing down an underground culvert.
• A faded mason's crest chiseled into a 19th-century lintel.
• An unexpected dirt trail cutting between two brick cul-de-sacs.

TRACE gives you an enduring, private place to record these moments as traces. Over time, your discoveries construct an illustrated, living map of where you paid attention. When local AI is enabled via LM Studio, open-weight models (such as Google Gemma 3 4B) synthesize your field notes, uncover hidden sensory patterns, and prompt where you might look next—all without sending a single coordinate, photo, or thought to cloud servers.

┌────────────────────────────────────────────────────────────────────────┐
│  CONVENTIONAL APPS                                                     │
│  [Screen] ──► [Infinite Feed] ──► [Notification Ping] ──► [More Screen]│
│                                                                        │
│  TRACE FIELD JOURNAL                                                   │
│  [Screen: Brief Spark] ──► [Step Outside & Observe] ──► [Living Map]   │
└────────────────────────────────────────────────────────────────────────┘

The TRACE exploration cycle bridges the digital interface with the living physical world:

flowchart LR
    A["🌿 1. Step Outside<br><i>Wander without a destination</i>"] --> B["🔎 2. Notice a Detail<br><i>Masonry, birdsong, flora</i>"]
    B --> C["📝 3. Capture Trace<br><i>Field note + photo/audio</i>"]
    C --> D["🧠 4. Local AI Lens<br><i>Gemma 3 4B synthesizes tags</i>"]
    D --> E["🗺️ 5. Living Map<br><i>Anchor discovery to canvas</i>"]
    E --> F["🐌 6. Sticker Garden<br><i>Earn daily field stamps</i>"]
    F -.->|Inspires next curiosity| A

1. Step Outside: Close the browser, put your phone in your pocket, and explore the physical world at human walking speed.
2. Notice a Detail: Shift attention to sensory observations: an unusual sound, an engineered remnant, or an overgrown corner.
3. Capture a Trace: Return to TRACE to write what you saw. Optionally pick an explicit category lens and attach a field photo or audio recording.
4. Local AI Synthesis: Your local Gemma model generates a concise field title, qualitative summary, and sensory tags. If you chose a category lens, your choice is strictly authoritative.
5. Living Map Placement: Anchor the trace using browser GPS, click directly on the map, or keep it unplaced in your memory log.
6. Sticker Garden & Rewards: If this is your first trace today, claim an illustrated field sticker, build your exploration streak, and unlock milestone packs.

Your physical discoveries, rendered as an illustrated cartographic canvas.

• Leaflet Spatial Canvas: Interactive, fluid map rendering customized with TRACE's vintage parchment aesthetic.
• Five Distinct Discovery Lenses:
  • 🌿 Nature: Plants, moss, fungi, wildlife, weather phenomena, and natural cycles.
  • 🔊 Sound: Bird calls, stream currents, industrial hums, acoustic echoes, and rhythms.
  • 🏛️ Structure: Bridges, old masonry, culverts, street furniture, and infrastructure.
  • 🔎 Mystery: Unexplained markings, out-of-place objects, and historical puzzles.
  • 💙 Personal: Meaningful spots, quiet benches, memories, and personal sanctuaries.
• Category Filter Bar: Filter by lens with single-click filter chips showing live counters of total discoveries.
• Flexible Placement: Drop markers via high-accuracy GPS, click anywhere for Manual Placement, or save notes as Unplaced Traces.

A focused field-journal entry tool engineered for rapid, tactile recording.

• Distraction-Free Field Notes: Simple text area designed for natural, evocative field descriptions.
• Category Precedence Rule: Choose an explicit category lens, or leave it unselected to let local AI auto-classify. User choices are authoritative and are never silently overwritten.
• Photo & Audio Attachments:
  • Photographs: JPEG, PNG, WebP, GIF with instant client-side thumbnail previews.
  • Audio Recordings: MP3, WAV, OGG, WebM, AAC, FLAC with an embedded in-browser audio player.
  • Magic-Byte Sniffing: Backend inspection verifies true file signatures rather than trusting client extensions.
  • Safety Boundaries: Strict filesystem sandboxing prevents path traversal, capped at 15 MB per file.
• Safe Cascading Deletions: Deleting a trace from your field notes permanently removes its record and cleanly purges associated media files from disk.

Open-weight intelligence running privately on your own hardware via LM Studio.

• Zero Cloud Dependency: Runs through LM Studio using standard OpenAI-compatible endpoints (http://127.0.0.1:1234/v1).
• Optimized for Google Gemma 3 4B: Tuned system prompts extract structured JSON (title, summary, tags, sensory_type, confidence).
• Deterministic Fallbacks: If LM Studio is paused or uninstalled, TRACE works without interruption, applying smart fallback titles and preserving full note fidelity.
• Absolute Privacy: Coordinates, journal entries, and media files are never transmitted to external cloud AI providers.

Cute is the aesthetic. Exploration is the purpose. Stickers are the reward.

• Daily Exploration Streaks: Logging a trace qualifies your calendar day. Streaks encourage slow, regular walks.
• Resilient Streak Rules: Missing a day resets the current streak counter, but your longest streak record is preserved forever, and earned stickers are never lost.
• Milestone Collections:
  • 🌿 The Little Things Club (7-day streak)
  • 📖 The Field Journal Collection (30-day streak)
  • 🐌 The Outside-ish Personality Pack (50-day streak)
  • 🗺️ The World Noticed Collection (100-day streak)
• Specimen Modal & High-Res Downloads: Inspect any collected card in an archival specimen frame and click Download PNG to save transparent sticker artwork to your device.
• Cross-Tab Synchronization: Real-time synchronization via BroadcastChannel and localStorage keeps streak counters and sticker rewards synced across all open browser tabs instantly.

Below is a preview of verified sticker illustrations bundled directly in TRACE:

Tiny Sprout	Rock Lichen	Unscheduled Snail
"Look at me, being alive and stuff."	"Taking things slow on a warm rock."	"Outside. Against my usual schedule."
Theme: Botanical • Common	Theme: Botanical • Common	Theme: Creatures • Common

(Stickers whose artwork is currently in illustration display a decorative field-stamp placeholder until transparent PNGs are added).

Get TRACE running locally in five minutes. Windows PowerShell is shown first, followed by macOS/Linux commands.

• Python: 3.11, 3.12, or 3.13 installed
• Node.js: v20.x or higher + npm
• Git: Installed and available in terminal
• LM Studio (Optional): Recommended for local Gemma 3 4B AI interpretation

# Windows PowerShell & macOS/Linux
git clone https://github.com/shiriei/TRACE.git
cd TRACE

In your first terminal window:

# Windows PowerShell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item ..\.env.example .env

# Start FastAPI server on port 8000
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

# macOS / Linux
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp ../.env.example .env

# Start FastAPI server on port 8000
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

The SQLite database (runtime/traces.db) initializes automatically on first boot.

In a second terminal window:

# Windows PowerShell & macOS/Linux
cd TRACE/frontend
npm install

# Start Vite development server
npm run dev

Open your browser to: http://localhost:5173

1. Download and launch LM Studio.
2. Search for and download Gemma 3 4B (e.g. google/gemma-3-4b-it GGUF).
3. Click the Developer / Local Server tab (<-> on the left sidebar).
4. Select and load the Gemma 3 4B model into memory.
5. Set port to 1234, enable CORS, and click Start Server.
6. TRACE will automatically detect the server and display an active local-AI status indicator.

• Backend Health: http://127.0.0.1:8000/api/v1/health returns {"status":"healthy"}.
• Swagger UI: http://127.0.0.1:8000/docs loads interactive OpenAPI documentation.
• Frontend Canvas: http://localhost:5173 displays the living map and field capture form.
• First Trace: Write an observation, select 🌿 Nature, save unplaced, and watch your first sticker unlock!

graph TB
    subgraph Browser Client [Frontend — React + TypeScript + Vite — :5173]
        Map[Leaflet Living Map Canvas]
        Capture[Trace Creation Form & Lens Chips]
        Garden[Sticker Garden & Specimen Modal]
        Sync[Cross-Tab Sync Engine]
    end

    subgraph FastAPIServer [Backend — Python 3.11+ — :8000]
        Router[API Routers: /traces, /ai, /stickers]
        TraceSvc[Trace Service & Dedup]
        StickerSvc[Sticker & Streak Engine]
        MediaSvc[Media Storage & Sniffer]
        AISvc[AI Parser & Schema Validator]
    end

    subgraph Storage [Local Storage Layer]
        DB[(SQLite 3: runtime/traces.db)]
        Files[(Media: runtime/media/)]
    end

    subgraph Inference [Local AI — LM Studio — :1234]
        Model[Gemma 3 4B Open-Weight Model]
    end

    Capture -->|POST /api/v1/traces| Router
    Capture -->|Stream Multipart Files| Router
    Router --> TraceSvc
    Router --> MediaSvc
    Router --> StickerSvc

    TraceSvc --> AISvc
    AISvc -->|POST /v1/chat/completions| Model
    Model -->|JSON Response| AISvc

    TraceSvc --> DB
    MediaSvc --> Files
    MediaSvc --> DB
    StickerSvc --> DB

    Router -->|Trace + Streak Reward| Capture
    Capture --> Map
    Capture --> Garden
    Sync <--> BrowserClient

sequenceDiagram
    autonumber
    actor Explorer as Explorer
    participant UI as Frontend (React)
    participant API as FastAPI Backend
    participant AI as LM Studio (Gemma 3)
    participant DB as SQLite Database
    participant Disk as Local Media Storage

    Explorer->>UI: Enter observation & select category lens
    Explorer->>UI: (Optional) Attach photo or voice note
    UI->>API: POST /api/v1/traces (observation, category, location)
    API->>DB: INSERT initial trace record
    
    alt LM Studio is Active
        API->>AI: POST /v1/chat/completions (Structured JSON Prompt)
        AI-->>API: {title, summary, tags, sensory_type, category}
        Note over API: Apply Precedence: Explicit user category overrides AI
    else LM Studio Offline
        Note over API: Apply deterministic fallback title & summary
    end

    API->>DB: UPDATE trace with metadata & final category
    API->>DB: Evaluate streak & check daily sticker qualification
    
    opt Attachments Uploaded
        UI->>API: POST /api/v1/traces/{id}/attachments (Multipart)
        API->>Disk: Sniff magic bytes & stream file (UUID)
        API->>DB: INSERT attachment metadata record
    end

    API-->>UI: 201 Created (Trace, Reward, Streaks)
    UI->>UI: Render pin on map & broadcast cross-tab sync
    UI->>Explorer: Trigger reward celebration modal

TRACE/
├── .env.example             # Configuration template for local overrides
├── LICENSE                  # MIT Open-Source License
├── README.md                # Comprehensive documentation & field guide
├── docs/
│   └── ARCHITECTURE.md      # Detailed system architecture specification
├── backend/
│   ├── requirements.txt     # Python dependencies (FastAPI, Uvicorn, Pydantic, etc.)
│   ├── app/
│   │   ├── main.py          # FastAPI application entrypoint & lifespan manager
│   │   ├── api/
│   │   │   ├── __init__.py  # Root API router mounting versioned routes
│   │   │   └── routes/      # Endpoints: /traces, /ai, /attachments, /stickers, /health
│   │   ├── core/
│   │   │   └── config.py    # Pydantic Settings & environment variable parsing
│   │   ├── db/
│   │   │   └── database.py  # SQLite connection manager, WAL mode, foreign keys
│   │   ├── models/          # Dataclasses & internal domain models
│   │   ├── schemas/         # Pydantic request/response validation schemas
│   │   ├── services/        # Business logic: trace_service, sticker_service, media_storage
│   │   ├── ai/              # LM Studio HTTP client, JSON schema parser, prompts
│   │   └── stickers/        # Sticker catalogue definitions & milestone packs
│   └── tests/               # 103 Pytest tests: test_traces, test_stickers, test_attachments, test_ai
└── frontend/
    ├── package.json         # Frontend dependencies & npm scripts
    ├── vite.config.ts       # Vite bundler configuration
    ├── index.html           # HTML entrypoint loading Fraunces & Inter fonts
    ├── public/
    │   ├── trace-mark.svg   # TRACE vector compass mark
    │   └── assets/stickers/ # Verified transparent PNG sticker illustrations
    └── src/
        ├── App.tsx          # Root application shell & cross-tab sync coordinator
        ├── index.css        # Field-journal design tokens & responsive styles
        ├── types/           # TypeScript interfaces (Trace, Sticker, Media)
        ├── services/        # Frontend API clients (api.ts, traceService.ts, stickerService.ts)
        ├── hooks/           # Custom React hooks (useStreak, useHealthStatus)
        └── features/
            ├── map/         # Living Trace Map, markers, detail card, thumbnails
            ├── ai/          # TraceAIInterpreter creation form & category lens chips
            └── stickers/    # StickerGardenJourney, StickerDetailModal, DailyRewardModal

# From the backend/ directory with .venv active
.\.venv\Scripts\pytest.exe -v

# From the frontend/ directory
npm run typecheck

# From the frontend/ directory
npm run build

TRACE is designed from first principles as a sovereign, local-first system:

1. Local Relational Storage: All traces, notes, coordinates, sensory types, and timestamps are persisted in runtime/traces.db (SQLite). Foreign keys (ON DELETE CASCADE) and Write-Ahead Logging (WAL) guarantee reliability and clean data integrity.
2. Local Media Sandboxing: Uploaded field photographs and audio captures are stored in runtime/media/ using random UUID filenames.
3. Zero Telemetry: TRACE does not include tracking scripts, Google Analytics, telemetry beacons, or advertising SDKs.
4. Offline Cartography Note: While observations and AI processing run 100% locally on your machine, the Leaflet map fetches public OpenStreetMap tiles over the internet when connected.
5. No Cloud Sync or Accounts: There are no remote user accounts or multi-user cloud synchronization services. Your field notes remain strictly on your computer.

• Sticker Artwork Coverage: High-resolution botanical and creature illustrations are currently bundled for Tiny Sprout, Rock Lichen, and Unscheduled Snail. Other catalogue items display the field-journal stamp fallback until additional artwork is illustrated.
• Local Model Hardware: Quality and speed of AI titles, summaries, and tags depend on the computing capacity of your machine. Google Gemma 3 4B is recommended for optimal speed and poetic observation synthesis.
• Cartographic Tile Fetching: The Leaflet map engine requires an internet connection to stream OpenStreetMap tiles unless an offline tile server is configured.
• Single-Explorer Architecture: TRACE is designed as a personal field notebook. Multi-user accounts, social feeds, and cloud sync are intentionally omitted by design.

We warmly welcome contributions from developers, writers, field naturalists, and designers who share our love for noticing the living world!

1. Fork the Repository: Create a personal fork of shiriei/TRACE on GitHub.
2. Create a Topic Branch:

   git checkout -b feature/sensory-audio-visualizer

3. Make Focused Changes: Preserve the vintage field-journal aesthetic, local-first sovereignty, and clean TypeScript/Python types.
4. Run Verification Commands:

   # Backend
   cd backend && pytest -v
   # Frontend
   cd ../frontend && npm run typecheck && npm run build

5. Submit a Pull Request: Detail your changes, testing methodology, and motivations.

The following exploratory horizons reflect potential future evolutions for TRACE:

• Spatial Territory Frontiers: Visualizing unexplored pockets and alleys in your immediate neighborhood where you have not yet left a trace.
• Adaptive Curiosity Cues: Subtle, enigmatic prompts inspired by your personal trace history (e.g., "You notice old masonry often. What sounds live near the brickwork?").
• Offline Map Tile Caching: Local tile caching to enable completely disconnected field exploration in remote valleys and forests.
• Expanded Catalogue Artwork: Additional hand-illustrated sticker rewards celebrating slow observation.

TRACE is open-source software licensed under the MIT License.

Copyright (c) 2026 TRACE Contributors

You are free to use, modify, distribute, and study this software in accordance with the terms of the MIT license.

TRACE was created for anyone who has ever walked past an old mossy wall, an overgrown alleyway, or an echo beneath a railway bridge and thought:

I want to remember that this was here.

Put your phone in your pocket. Go outside. Notice more. Leave a trace.