WB Plan

WhiteBlazeFieldReports.com Implementation Plan

For Hermes: Use subagent-driven-development if implementing this plan task-by-task. This is a planning-only document; do not implement until explicitly asked.

Goal: Build a public-facing Appalachian Trail unusual-phenomenon field report website with a map-first home page, quick sighting statistics, browsable demo reports, and a new report submission workflow.

Architecture: Start as a fast, content-rich MVP with a static/front-end application backed by a small database/API for reports. The home page centers on a simplified Appalachian Trail map with clustered report markers and high-level statistics. Reports flow through a moderation pipeline before becoming public.

Recommended MVP Tech Stack:

Frontend: Next.js 15 + React + TypeScript + Tailwind CSS
Map: MapLibre GL with polished terrain/topographic vector tiles for the best end-user visual experience; AT corridor represented by simplified GeoJSON
Backend/API: Next.js Route Handlers backed by the existing MySQL database
Database: Existing MySQL instance at localhost:3304, user website, password test1, database test1-mgaif; use Prisma for typed access and migrations
Auth/Admin: Application-managed admin auth, e.g. Auth.js/NextAuth Credentials or signed admin sessions stored in MySQL; public users can submit without accounts
Validation: Zod schemas shared between client and server
File Uploads: Application-managed uploads using local/object storage metadata stored in MySQL; photos/audio/video gated by size/type limits
Testing: Vitest + React Testing Library + Playwright
Deployment: Each requested build/release is delivered to the existing test webroot /home/mgaif-test1/htdocs/test1.mgaif.com, connected to the existing MySQL database; uploads stored on configured local/object storage

Release/Test Delivery Target

Every milestone should be releasable to the existing test directory:

/home/mgaif-test1/htdocs/test1.mgaif.com

Deployment assumptions and rules:

This directory is already served by nginx.
SSL is already handled by a reverse proxy in front of nginx.
When a build/release is requested, deliver the built site/application artifacts to /home/mgaif-test1/htdocs/test1.mgaif.com.
The test directory can be emptied for each release before copying the new build artifacts.
Do not change nginx or reverse-proxy configuration unless explicitly requested.
Each milestone should include a release verification step against the test deployment target after the build is copied.
If the app requires a long-running Node.js process instead of static files, include a process manager/startup step in the milestone release notes while still using /home/mgaif-test1/htdocs/test1.mgaif.com as the release directory.

1. Product Definition

1.1 Site Concept

WhiteBlazeFieldReports.com is a serious research archive for unusual phenomena, organized around the Appalachian Trail as its main identity and discovery anchor. The site should feel like a blend of:

A backcountry field notebook
A public reporting database
A simple incident/sighting map
A serious anomalous-observation research archive

The site should avoid making factual claims that reports are true. Language should frame entries as submitted reports, field observations, or witness accounts.

1.2 Core User Groups

Casual visitors

** Want to browse strange trail reports. ** Want an immediate map and quick stats. ** May filter by state, phenomenon type, date, or trail section.

Hikers / witnesses

** Want to submit a report from memory or soon after an event. ** Need a reassuring form that supports uncertainty. ** May want location privacy.

Moderators / researchers

** Need to perform an initial publication check quickly. ** Need to classify, redact, approve for public viewing, reject, or request more detail. ** Need to continue verification/research after a report is already public, with the report clearly flagged as unverified until reviewed. ** Need to identify obvious hoaxes, duplicates, and explainable sightings.

Trail researchers / enthusiasts

** Want structured data, indexes, patterns, and historical browsing. ** May care about trail mile, nearest shelter, weather, moon phase, season, etc.

1.3 Content Scope

Reports should be accepted for unusual observations from anywhere, while the site still focuses its presentation, branding, and discovery experience around the Appalachian Trail. Submissions must include the GPS coordinates of the event/report location — the place where the phenomenon happened — not the submitter’s current location or the device location at submission time. Reports can later be classified by distance to the Appalachian Trail corridor, such as on trail, near trail, regional, or outside AT corridor.

Accepted report types include:

Unidentified lights or aerial objects
Strange sounds or vocalizations
Unusual animal encounters
Apparitions / figures / shadow sightings
Missing-time or disorientation experiences
Odd weather, atmospheric, or light phenomena
Campsite disturbances
Trail folklore-adjacent reports
Physical traces, tracks, odors, or environmental anomalies

Reports should not be positioned as emergency dispatch, search-and-rescue, law enforcement, medical advice, or proof of paranormal activity.

2. Inspiration From Similar Reporting Systems

Research notes from comparable public reporting systems:

2.1 NUFORC-style UFO Reporting

Observed design/product patterns:

Top navigation with Data Bank, Map, Gallery, File a Report, About.
Public map page using map markers.
Report submission page begins with guidance about common misidentifications.
Report database includes categorization and reviewer grading.
Reports are public, but framed as submitted witness accounts.
Useful indexing options: date, location, type/shape, date posted.

Adapt for WhiteBlazeFieldReports.com:

Add a Field Reports, Map, Submit Report, Data Bank, Guide, and About nav.
Add pre-submit guidance for common trail explanations: headlamps, aircraft, satellites, owls, foxes, bear activity, infrasound/wind, trail runners, drones, weather inversions, campfire reflections.
Include moderator confidence and explainability labels.

2.2 BFRO-style Encounter Reporting

Observed design/product patterns:

Long-form witness form.
Encourages as much detail as possible.
Allows private researcher contact.
Warns against joke/hoax reports.
Keeps a traditional, archive-like aesthetic.

Adapt for WhiteBlazeFieldReports.com:

Use a friendly but serious report form.
Encourage narrative detail before memory fades.
Let submitters choose public/private contact preferences.
Require GPS coordinates for the event/report location, while supporting non-public exact coordinates and approximate public display coordinates.
Use an archive/field-guide visual style without copying outdated table layouts.

2.3 Citizen-Science Observation Sites

Relevant patterns from platforms like iNaturalist/eBird-style systems:

Observations have time, place, media, observer notes, and community/reviewer annotations.
Map browsing is central.
Filtering and taxonomy/category systems are important.
Quality grades or verification states help users understand data reliability.

Adapt for WhiteBlazeFieldReports.com:

Use structured metadata plus narrative.
Add workflow status labels: Submitted, Initial Check, Public / Unverified, Verified / Researched, Explained, Archived, Rejected.
Add public reliability labels that avoid overclaiming: Not Verified Yet, Under Review, Reviewed Unresolved, Likely Natural, Likely Human-made, Insufficient Detail.

3. Visual and UX Design Direction

3.1 Brand Positioning

White Blaze references the Appalachian Trail’s iconic white trail markers. The brand should feel:

Appalachian
Archival
Field-research oriented
Slightly mysterious but not sensationalist
Useful on mobile in low-bandwidth contexts

3.2 Visual Style

Recommended look:

Background: warm off-white / aged paper, with subtle contour-map texture.
Primary color: white-blaze off-white on deep forest green.
Accent colors: amber for active sightings, rust for high-strangeness, blue-gray for unresolved, muted red for urgent/notable.
Typography: ** Headings: sturdy serif or slab serif, e.g. Source Serif, Merriweather, or Lora. ** Body/UI: legible sans, e.g. Inter, Atkinson Hyperlegible, or IBM Plex Sans.
UI motifs: field tags, paper cards, topo lines, trail-mile badges, state abbreviations, compass icons.
Map style: subdued terrain/forest tiles with a highlighted AT corridor line and report pins.

3.3 Home Page Layout

** Logo: vertical white blaze mark + WhiteBlazeFieldReports.com ** Nav: Map, Reports, Submit, Data Bank, Guide, About ** CTA button: Submit a Field Report

Hero section

** Title: Unusual Field Reports from the Appalachian Trail ** Subtitle: A map-based archive of strange lights, sounds, sightings, and unexplained trail experiences reported by hikers and observers. ** CTA buttons: Explore the Map, File a Report

Summary map panel

** Simplified Appalachian Trail line from Georgia to Maine. ** Markers clustered by region/state. ** Marker color by phenomenon category. ** Hover/click summary cards. ** Mobile fallback: state/section list below mini-map.

Quick stats row

** Total publicly viewable reports ** Reports this year ** Most active state ** Most common category ** Unresolved reports ** Reports with media

Featured / latest reports

** 3-6 report cards with title, state, trail section, category, date, short excerpt, status label.

Report categories strip

** Lights in sky ** Strange sounds ** Unknown animal ** Figures / apparitions ** Campsite disturbance ** Environmental anomaly

How reporting works

** Submit details. ** Moderators review/redact. ** Public archive updates.

** Disclaimer, privacy, contact, terms, data policy.

4. Information Architecture

4.1 Public Pages

/ — Home page with map, stats, latest reports.
/map — Full-screen interactive map with filters.
/reports — Searchable/browsable report list.
/reports/[slug] — Report detail page.
/submit — New report submission form.
/data-bank — Indexes by state, date, category, trail section, status.
/guide — Reporting guide and common explanations.
/about — Mission, moderation policy, disclaimers.
/privacy — Privacy and location redaction policy.
/terms — Terms of use and acceptable submissions.

4.2 Admin Pages

/admin/login — Moderator login.
/admin — Review dashboard.
/admin/reports — Submission queue.
/admin/reports/[id] — Review/edit/redact/approve report.
/admin/taxonomy — Manage categories, trail sections, tags.
/admin/demo-data — Seed/remove demo reports in non-production environments.

4.3 Application API Endpoints

These endpoints are for the website application itself. They should not be marketed as a public API, and the MVP should not include bulk download/export endpoints.

GET /api/reports — Paginated public report list.
GET /api/reports/[slug] — Public report detail.
POST /api/reports — Public report submission.
GET /api/stats — Home page stats.
GET /api/map/reports — Map marker payload.
GET /api/trail/sections — Trail section metadata.
POST /api/uploads/sign — Signed media upload URL, if using direct-to-storage uploads.
GET /api/admin/reports — Admin queue.
PATCH /api/admin/reports/[id] — Admin moderation updates.

5. Core Data Model

5.1 `reports`

Fields:

id UUID primary key
slug unique text
public_title text
summary text
narrative text
phenomenon_category_id FK
event_started_at timestamp nullable
event_ended_at timestamp nullable
event_date_precision enum: exact, approximate, month_only, year_only, unknown
submitted_at timestamp
published_at timestamp nullable
status enum: submitted, initial_check, public_unverified, verified_researched, explained, archived, rejected
review_label enum: not_verified_yet, under_review, reviewed_unresolved, likely_natural, likely_human_made, insufficient_detail, duplicate, hoax_likely
strangeness_score integer 1-5 nullable
confidence_score integer 1-5 nullable
state text nullable, derived from event/report GPS coordinates when possible
country text nullable, derived from event/report GPS coordinates when possible
report_lat numeric required restricted/private — exact GPS latitude of where the event happened, not where the form was submitted
report_lng numeric required restricted/private — exact GPS longitude of where the event happened, not where the form was submitted
distance_to_at_miles numeric nullable — calculated distance from report location to nearest Appalachian Trail route point when route data is available
at_proximity_class enum: on_trail, near_trail, regional, outside_corridor, unknown
trail_section_id FK nullable
nearest_town text nullable
nearest_shelter_or_landmark text nullable
at_mile numeric nullable
lat_public numeric nullable — fuzzed/rounded public latitude derived from report_lat
lng_public numeric nullable — fuzzed/rounded public longitude derived from report_lng
location_accuracy enum: exact, within_0_5_mile, within_2_miles, nearest_landmark, state_only
public_location_label text
weather text nullable
moon_phase text nullable
group_size integer nullable
witness_count integer nullable
duration_seconds integer nullable
media_count integer default 0
is_demo boolean default false
show_in_demo_mode boolean default false
submitter_contact_encrypted text nullable
submitter_public_name text nullable
submitter_privacy_preference enum: anonymous, first_name, trail_name, full_name
moderator_notes text private nullable
created_at timestamp
updated_at timestamp

5.2 `phenomenon_categories`

Seed categories:

lights_sky — Lights / aerial objects
strange_sounds — Strange sounds / vocalizations
unknown_animal — Unknown animal / cryptid-like encounter
figures_apparitions — Figures / apparitions
campsite_disturbance — Campsite disturbance
environmental_anomaly — Weather / light / environmental anomaly
tracks_traces — Tracks / traces / physical evidence
time_disorientation — Missing time / disorientation
other — Other unusual event

5.3 `trail_sections`

Fields:

id
name
state
start_mile
end_mile
description
center_lat
center_lng
geojson_simplified

Initial MVP can seed one broad section per AT state. Later versions can add parks, trail clubs, shelters, and mile markers.

5.4 `media_assets`

Fields:

id
report_id
type: photo, audio, video, document
storage_path
public_url nullable
caption
metadata_json
is_public
created_at

5.5 `moderation_events`

Fields:

id
report_id
moderator_user_id
from_status
to_status
notes
created_at

5.6 `admin_users`

Fields:

id
email unique
password_hash nullable if using external auth later
display_name
role enum: admin, moderator, researcher
is_active
created_at
updated_at

5.7 `admin_sessions` / Auth.js tables

Use either Auth.js-compatible MySQL tables or a minimal signed-session table. Store only admin/moderator sessions; public submitters do not need accounts.

5.8 MySQL implementation notes

Use Prisma with provider = "mysql" and DATABASE_URL="mysql://website:test1@localhost:3304/test1-mgaif".
Use Decimal or Double columns for lat/lng in MVP; optionally add MySQL POINT SRID 4326 columns later if spatial indexes are needed.
Prefix or clearly name WhiteBlaze tables if the existing test1-mgaif database already contains unrelated application tables.
Migrations must be additive and must not drop or alter unrelated existing tables.

6. New Report Submission Flow

6.1 Form Sections

Before you begin

** Explain purpose. ** Ask user not to submit jokes/hoaxes. ** Explain moderation and location redaction. ** Link to common explanations.

What happened?

** Category ** Short title ** Detailed narrative ** Duration ** Number of witnesses ** Was it seen/heard directly or captured only by camera/audio?

When did it happen?

** Date/time ** Precision controls for uncertain memory ** Time zone default based on location

Where did it happen?

** Required GPS coordinates for the event/report location, not the user’s current/reporting location ** Map picker with manual latitude/longitude entry ** Explicit helper text: Use the location where the sighting or event happened. Do not enter where you are submitting from unless it is the same place. ** Optional state/country derived by reverse geocoding or selected manually if geocoding fails ** Trail mile if known ** Nearest shelter, road crossing, town, peak, gap, campsite, or landmark ** Public location precision choice

Conditions

** Weather ** Visibility ** Moon/sky conditions ** Wind ** Nearby people/campsites ** Known possible explanations noticed

Media

** Optional photo/audio/video upload ** Require permission checkbox ** Strip EXIF metadata before public display

Contact and privacy

** Anonymous option ** Trail name option ** Email for moderator follow-up, not public ** Consent checkboxes

Review and submit

** Summary preview ** Anti-spam challenge/honeypot ** Submit

6.2 Post-Submit UX

Confirmation page: Report received.
Explain that no email verification is required.
Explain the publication workflow: a moderator performs an initial safety/spam/privacy check, then the report can become public as Not Verified Yet while research continues.
Provide report reference ID.
Offer optional copy of submitted report by email.
Do not publish automatically in production; publication requires the initial moderator check.

7. Map Design

7.1 Home Page Summary Map

MVP requirements:

Display simplified Appalachian Trail route as a highlighted polyline.
Display report markers using approximate public coordinates.
Display all public reports that have public coordinates, including reports outside the AT corridor; visually distinguish on_trail, near_trail, regional, and outside_corridor reports.
Cluster markers when zoomed out.
Clicking a marker opens a mini report card.
The map should not reveal private/exact coordinates when a submitter requested privacy.
Initial viewport should include the entire AT corridor from Georgia to Maine.
If filters include outside-corridor reports, allow map bounds to expand beyond the AT corridor while keeping the AT line visible as the site anchor.

7.2 Full Map Page

Filters:

Category
State
Trail section
Date range
Review label
Has media
Strangeness score
Publicly viewable/demo only
Include demo reports toggle, defaulting off in production and on only in seeded demo/dev contexts.

Map interactions:

Marker click opens side panel.
List view syncs with map viewport.
Reset filters button.
Shareable URL query params.

7.3 AT Geo Data Strategy

MVP choice:

Chosen for MVP: Use MapLibre GL with a polished terrain/topographic vector style and a simplified AT GeoJSON line. This is the best-looking end-user option while remaining practical.

Fallback: If vector tile cost/API-key constraints become a problem, use Leaflet with high-quality raster terrain tiles.

Later: Store full route geometry using MySQL spatial columns/functions or precomputed route-segment tables and calculate nearest trail mile.

For MVP, use option 1. Avoid overbuilding mile-calculation until the basic product works.

8. Demo Reports for MVP

Include demo reports to showcase the site without implying verified real incidents. Each demo report must be clearly labeled: Demo report for product preview.

8.1 Demo Report Set

Seed 10-12 demo reports across the AT:

Blue Ridge Lights Above Blood Mountain

** State: Georgia ** Category: Lights / aerial objects ** Location: near Blood Mountain ** Label: Reviewed unresolved

Three-Part Whistle Near Standing Indian

** State: North Carolina ** Category: Strange sounds ** Location: near Standing Indian Mountain ** Label: Insufficient detail

Orange Glow Over Max Patch

** State: North Carolina / Tennessee ** Category: Environmental anomaly ** Location: Max Patch area ** Label: Likely natural

Footsteps Circling Camp at Roan Highlands

** State: Tennessee ** Category: Campsite disturbance ** Location: Roan Highlands ** Label: Reviewed unresolved

Dark Figure at Grayson Highlands

** State: Virginia ** Category: Figures / apparitions ** Location: Grayson Highlands ** Label: Not Verified Yet

Metallic Hum Near Shenandoah Wayside

** State: Virginia ** Category: Strange sounds ** Location: central Shenandoah ** Label: Likely human-made

Trackway After Rain Near Pine Grove Furnace

** State: Pennsylvania ** Category: Tracks / traces ** Location: Pine Grove Furnace area ** Label: Insufficient detail

White Light Moving Along Kittatinny Ridge

** State: New Jersey ** Category: Lights / aerial objects ** Location: Kittatinny Ridge ** Label: Reviewed unresolved

Lost Time on Bear Mountain Descent

** State: New York ** Category: Missing time / disorientation ** Location: Bear Mountain ** Label: Likely natural

Mist Column Near Mount Greylock

*** State: Massachusetts *** Category: Environmental anomaly *** Location: Mount Greylock *** Label: Not Verified Yet

Knocking Sounds in the Whites

*** State: New Hampshire *** Category: Strange sounds *** Location: White Mountains *** Label: Reviewed unresolved

Distant Blue Flashes Below Katahdin

*** State: Maine *** Category: Lights / aerial objects *** Location: near Katahdin approach *** Label: Not Verified Yet

8.2 Demo Data Requirements

Each seeded demo report should include:

Title
Short summary
300-700 word narrative or shorter MVP narrative
Approximate public lat/lng
State
Trail section
Category
Event date
Published date
Review label
Strangeness score
Confidence score
Witness count
Weather note
is_demo: true
show_in_demo_mode: true

8.3 Demo Toggle Requirements

Demo reports should be hidden by default in production public views unless the user enables a Show demo reports toggle.
Demo reports may be visible by default in local development and staging.
The toggle should affect the home map, quick stats, reports list, full map, and data-bank counts.
Demo reports must remain clearly labeled on cards and detail pages even when the toggle is enabled.

9. First MVP Definition

9.1 MVP Goal

A visitor should be able to land on WhiteBlazeFieldReports.com, understand the concept within 10 seconds, explore a map of demo Appalachian Trail reports, read report details, and submit a new report into a moderation queue.

9.2 MVP Must-Haves

Branded responsive site shell.

Home page with hero, AT summary map, stats, and latest reports.

Public reports list with filtering by category/state.

Report detail pages.

Submit report form with validation, required event GPS coordinates, and media uploads.

Database schema for reports/categories/sections/media metadata.

Demo data seed script with production-safe demo toggle support.

Admin-only moderation queue with approve-for-public-unverified/reject/edit basics.

Privacy-safe location handling.

Basic tests for validation, report submission, media upload validation, rendering, demo toggle behavior, and map payloads.

Deployment-ready environment configuration.

9.3 Explicitly Out of Scope for MVP

User accounts for public submitters.
Public comments/discussion.
Public API endpoints intended for third-party consumption or bulk data downloads.
Offline/PWA submission drafts.
Advanced nearest-trail-mile calculation.
AI classification or automatic debunking.
Complex media processing beyond safe upload and optional EXIF stripping.
Native mobile app.
Real-time alerts.
Paid memberships or donations.

10. Milestones

Release rule for every milestone:

Each milestone should end with a build/release candidate that can be delivered to /home/mgaif-test1/htdocs/test1.mgaif.com when requested.
The release process may empty /home/mgaif-test1/htdocs/test1.mgaif.com before copying the new build artifacts.
Because nginx and SSL reverse proxy are already configured, milestone delivery should focus only on application build artifacts, runtime configuration, and verification.
After delivery, perform a smoke test through the configured test site URL/path served from that directory.

Milestone 0: Project Foundation

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Clean application scaffold with linting, tests, styling, and deployment settings.

Tasks:

Initialize Next.js + TypeScript project.

Add Tailwind CSS and design tokens.

Configure ESLint, Prettier, Vitest, Playwright.

Add environment variable templates.

Add MySQL database access setup using Prisma.

Add base layout, metadata, SEO defaults.

Add CI workflow for lint/test/build.

Acceptance criteria:

npm run lint passes.
npm run test passes.
npm run build passes.
Home placeholder renders locally.

Milestone 1: Brand and Static Shell

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Website looks like WhiteBlazeFieldReports.com before data integration.

Tasks:

Create logo treatment using white blaze mark.

Define color palette and CSS variables.

Build header/nav/footer.

Build reusable UI components: Button, Card, Badge, StatCard, SectionHeading, FormField, EmptyState.

Create placeholder pages for Home, Map, Reports, Submit, Data Bank, Guide, About.

Acceptance criteria:

Site has coherent brand and navigation.
Mobile and desktop layouts are usable.
Lighthouse accessibility score should be 90+ for static shell.

Milestone 2: Data Model and Demo Seeds

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: The existing MySQL database can store report data and seed demo content.

Existing DB target:

Host: localhost
Port: 3304
User: website
Password: test1
Database: test1-mgaif
Recommended env var: DATABASE_URL="mysql://website:test1@localhost:3304/test1-mgaif"

Tasks:

Create database migration for `phenomenon_categories`.

Create migration for `trail_sections`.

Create migration for `reports`.

Create migration for `media_assets`.

Create migration for `moderation_events`.

Add application-level authorization rules for private fields and admin-only mutations, since MySQL does not provide Supabase-style RLS.

Add seed file for categories.

Add seed file for state-level AT sections.

Add seed file for 10-12 demo reports.

Add script to reset/reseed local demo data.

Acceptance criteria:

Existing MySQL database can be migrated and seeded.
Demo reports appear in database.
Repository/API tests prove public queries cannot access private submitter contact or private exact report coordinates.
Report records require report_lat and report_lng for the event/report location; submission capture must not silently use the submitter’s current device location as a substitute.

Milestone 3: Application Report APIs

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Frontend can retrieve reports, stats, and map markers from typed APIs.

Tasks:

Define shared Zod schemas for public report DTOs.

Implement `GET /api/reports` with pagination and filters.

Implement `GET /api/reports/[slug]`.

Implement `GET /api/stats`.

Implement `GET /api/map/reports`.

Add unit tests for query parsing and response shaping.

Add integration tests with seeded demo data.

Acceptance criteria:

Application endpoints return only public-safe fields and are not documented as a third-party public API.
Public browsing includes reports that passed initial check as public_unverified, plus verified/researched or explained reports.
No bulk download/export endpoint is included.
Filters work for state/category/date.
Stats match seeded data and respect the production demo toggle.

Milestone 4: Home Page and Summary Map

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: The home page showcases the basic website.

Tasks:

Build hero section.

Build quick stats section.

Add simplified AT GeoJSON asset.

Build `TrailSummaryMap` component.

Add marker rendering and clustering.

Add marker popup/report card.

Build latest reports section.

Add category strip.

Add loading and empty states.

Add responsive map fallback for mobile.

Acceptance criteria:

Home page renders real public reports plus demo reports only when the demo toggle is enabled.
Stats display correct totals and respect whether demo reports are shown or hidden.
Clicking a marker links to a report detail page.
Map uses MapLibre GL with a polished terrain/topographic visual style unless fallback constraints require Leaflet.
Mobile layout remains readable.

Milestone 5: Reports List and Detail Pages

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Users can browse and read field reports.

Tasks:

Build reports list page.

Add filter controls for state/category/review label.

Add report cards.

Add pagination.

Build report detail layout.

Add metadata panel: date, location, category, review label, witnesses, duration.

Add privacy-aware map snippet on detail page.

Add schema.org structured data where appropriate, avoiding unsupported truth claims.

Acceptance criteria:

Demo reports are browsable.
Filter results update correctly.
Report detail page does not expose private coordinates/contact fields.

Milestone 6: Submission Form

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Public users can submit a report into a non-public review queue.

Tasks:

Build form route `/submit`.

Add form stepper or sectioned long form.

Add client-side Zod validation.

Add server-side Zod validation.

Implement `POST /api/reports`.

Add spam honeypot field.

Add rate limiting by IP/session if available.

Add location privacy controls.

Add MVP media upload support for photos/audio/video with size/type restrictions.

Strip image EXIF metadata before public display when technically feasible in MVP.

Add confirmation page.

Add tests for required fields, invalid payloads, media upload validation, and successful submission.

Acceptance criteria:

Invalid forms show helpful errors.
Missing event/report GPS coordinates block submission with clear helper text.
Email verification is not required to submit a report.
Successful submissions land in submitted or initial_check, not public.
Media uploads are allowed in MVP and remain non-public until the report/media passes initial moderation.
Submitter contact is not exposed publicly.

Milestone 7: Admin Moderation MVP

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: A moderator can perform the initial check that makes a report publicly viewable as unverified, then continue research/verification later.

Tasks:

Configure application-managed admin auth against MySQL-backed users/sessions.

Add protected admin layout.

Build admin report queue.

Build admin report detail/editor.

Add status transition controls.

Add public title/summary editing.

Add `Approve for public viewing as Not Verified Yet` action.

Add later verification/research status controls.

Add private moderator notes.

Add location redaction tools.

Add media review controls for submitted uploads.

Log moderation events.

Add authorization tests for admin endpoints.

Acceptance criteria:

Non-admin users cannot access admin pages or APIs.
Moderator can approve a submitted report for public viewing as Not Verified Yet after initial check.
Moderator can later update a public report’s research/review label.
Moderation event history records changes.

Milestone 8: Full Map and Data Bank

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: Users can explore the archive beyond the home page.

Tasks:

Build full `/map` page.

Add side panel list synced with markers.

Add filters and shareable query params.

Build `/data-bank` index landing page.

Add index by state.

Add index by category.

Add index by event year/month.

Add index by review label.

Add demo toggle support to map and data-bank indexes.

Acceptance criteria:

Full map supports filtering.
Data Bank pages expose multiple useful browsing paths.
Demo reports are hidden by default in production and included only when the toggle is enabled.

Milestone 9: Guide, Policy, and Trust Layer

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: The site communicates responsible reporting standards.

Tasks:

Write `/guide` page with reporting tips.

Add common explanations checklist.

Write moderation policy.

Write privacy policy focused on location/contact handling.

Write terms / acceptable use.

Add report abuse/contact mechanism.

Add disclaimers to report pages.

Acceptance criteria:

Visitors understand that reports are submitted accounts, not verified proof.
Submitters understand privacy and moderation.

Milestone 10: QA, Launch, and Monitoring

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts.

Outcome: MVP is stable enough to share.

Tasks:

Run unit tests.

Run Playwright happy-path tests.

Test mobile layouts.

Test map marker interactions.

Test form validation and submission.

Verify environment variables for the test deployment.

Configure error monitoring.

Configure analytics with privacy-friendly defaults.

Build the release artifacts.

Empty `/home/mgaif-test1/htdocs/test1.mgaif.com` if a clean release is requested.

Copy the new build/release artifacts into `/home/mgaif-test1/htdocs/test1.mgaif.com`.

Verify nginx/reverse-proxy-served test site responds without changing nginx or SSL proxy configuration.

Seed demo reports with clear demo labels and keep them hidden by default behind the demo toggle.

Acceptance criteria:

Build passes.
Core user flows pass on the nginx/reverse-proxy-served test deployment.
Public pages do not expose private fields.
Requested releases are delivered to /home/mgaif-test1/htdocs/test1.mgaif.com, which may be emptied before each release.

Milestone 11: Design Review and Visual Polish

Implementation status: Completed. Recorded in MILESTONES.md and src/lib/milestones.ts. The polish pass normalized typography, converted latest/report archive cards to wide list rows, constrained the map page layout, improved filter spacing, and made /reports dropdown filters auto-submit.

Outcome: The full site receives a cohesive design review and polish pass so the MVP feels less prototype-like, has normalized typography and spacing, and presents reports in easier-to-scan layouts.

Context / current observations to address:

The entire website needs a design review to make it more polished, visually attractive, and consistent.

Font sizes, heading sizes, card text sizes, form text sizes, and supporting copy should be normalized across the site.

The card/grid style currently used for the home page “Latest reports” section and the `/reports` tab should be replaced with a list-style report presentation.

Report list items should be wide, multi-line rows that use the available column width instead of narrow card tiles.

The `/map` page map currently stretches to the full page width and looks distorted/funny; it should be constrained to a better visual proportion and composed with the side panel more intentionally.

The `/reports` page dropdown controls sit too close to their labels; label/control spacing needs to be improved.

The `/reports` page should remove the explicit submit/apply button. Changing any dropdown selection should update the filtered results automatically.

Tasks:

Audit the current pages visually: `/`, `/reports`, `/reports/[slug]`, `/map`, `/data-bank`, `/submit`, `/guide`, `/about`, and admin pages.

Define a normalized typography scale for h1/h2/h3, body text, metadata, badges, form labels, form controls, and fine print.

Update global CSS tokens and component styles to use the normalized typography scale.

Replace report card grids on the home page latest reports section with a wide list-row component.

Replace the `/reports` archive card grid with the same wide multi-line report list-row component.

Ensure each report row includes review label, title, state, trail section, category, date, summary, media indicator, and a clear “read report” link.

Improve mobile behavior for report list rows so they remain stacked/readable on narrow screens.

Redesign the `/map` layout so the map is not stretched awkwardly across the page; constrain its max width/aspect ratio and place filters/side panel in a balanced layout.

Improve `/map` side-panel spacing and scrolling behavior if the report list is long.

Increase spacing between dropdown labels and controls on `/reports` and any shared filter-control styles.

Remove the `/reports` page apply/submit button from the filter form.

Make `/reports` dropdown changes auto-update the filtered results, preferably with accessible progressive enhancement: a client component can submit on change while preserving usable form semantics.

Add/adjust tests for report list-row source hooks, absence of the reports submit button, filter auto-submit behavior, map aspect-ratio/constrained layout hooks, and typography token changes.

Run `npm run format:check`, `npm test`, `npm run lint`, `npm run build`, then deploy and visually verify live pages.

Acceptance criteria:

The initial MVP milestones 0–10 remain marked complete.
Milestone 11 is marked complete and no currently planned milestones remain pending.
Site typography is visibly more consistent across pages.
Home latest reports and /reports archive use wide list-style rows rather than card grids.
/map uses a constrained, intentional map layout that no longer appears stretched awkwardly.
Report filter labels and dropdowns have comfortable spacing.
/reports filters update when a dropdown selection changes without requiring a separate submit/apply button.
Mobile and desktop layouts remain readable.
Tests, lint, and production build pass before release.

11. Post-MVP Implementation Task List

Phase A: Repository Setup

Create Next.js app scaffold in the repository root.

Install Tailwind CSS.

Add TypeScript strict configuration.

Add ESLint/Prettier config.

Add Vitest config.

Add Playwright config.

Add `README.md` setup instructions.

Add `.env.example`.

Add GitHub Actions CI workflow.

Verify lint/test/build commands.

Phase B: Design System

Add CSS variables for brand colors.

Add font configuration.

Create `components/ui/Button.tsx`.

Create `components/ui/Card.tsx`.

Create `components/ui/Badge.tsx`.

Create `components/ui/StatCard.tsx`.

Create `components/layout/Header.tsx`.

Create `components/layout/Footer.tsx`.

Create responsive page container component.

Add static visual regression screenshot baseline if desired.

Phase C: Database and Types

Add `DATABASE_URL="mysql://website:test1@localhost:3304/test1-mgaif"` to local runtime configuration (`.env.local`), and document the same required shape in `.env.example` without committing secrets if this becomes a real repository.

Use Prisma as the MySQL ORM/query layer.

Connect to the existing MySQL database and verify credentials before writing migrations.

Create migrations for the WhiteBlaze tables without dropping unrelated existing database objects.

Add generated database types.

Add Zod schema for report submission.

Add Zod schema for public report response.

Add category seed data.

Add trail-section seed data.

Add demo report seed data.

Add demo visibility fields and demo toggle defaults.

Add seed verification script.

Add application-authorization tests/manual verification checklist for private fields and admin-only writes.

Phase D: Public Data Fetching

Create Prisma client/helper for MySQL.

Create report repository module.

Add `listPublicReports` function.

Add `getPublicReportBySlug` function.

Add `getPublicStats` function.

Add `getPublicMapMarkers` function.

Unit test repository mapping.

Implement API routes.

Add API integration tests.

Phase E: Home Page MVP Showcase

Build hero component.

Build stats component.

Add AT simplified GeoJSON asset.

Build MapLibre GL map wrapper with polished terrain/topographic style.

Render AT polyline.

Render public report markers.

Add demo report toggle and marker visibility behavior.

Build latest report cards.

Build category summary strip.

Add loading/empty/error states.

Phase F: Browsing and Detail

Build report list page layout.

Add filter state handling.

Add filter URL query serialization.

Add report cards.

Add pagination component.

Build report detail route.

Add report metadata component.

Add location privacy display component.

Add tests for list and detail pages.

Phase G: Submission

Build submit page copy and warning text.

Build form fields for narrative.

Build date/time fields.

Build location fields.

Build conditions fields.

Build privacy/contact fields.

Add validation messages.

Implement server submission route.

Add anti-spam honeypot.

Add media upload fields and signed upload flow.

Add file size/type validation.

Add confirmation page.

Add submission tests.

Phase H: Admin Moderation

Add application-managed admin auth config backed by MySQL.

Add admin route guard.

Build queue page.

Build report review page.

Add edit form.

Add status controls.

Add initial-check approval action that makes reports public as `Not Verified Yet`.

Add later research/verification label editing.

Add media review controls.

Add reject/archive actions.

Add moderation event insert.

Add authorization tests.

Add admin smoke test.

Phase I: Launch Hardening

Add privacy policy.

Add terms.

Add guide page.

Add sitemap generation.

Add robots.txt.

Add Open Graph images.

Add error monitoring.

Add analytics.

Run accessibility pass.

Run deployment checklist for `/home/mgaif-test1/htdocs/test1.mgaif.com`.

12. Files Likely to Be Created or Modified

Assuming a Next.js implementation:

README.md
.env.example
package.json
prisma/schema.prisma
prisma/migrations/*
tsconfig.json
next.config.ts
tailwind.config.ts
postcss.config.js
eslint.config.mjs
playwright.config.ts
vitest.config.ts
src/app/layout.tsx
src/app/page.tsx
src/app/map/page.tsx
src/app/reports/page.tsx
src/app/reports/[slug]/page.tsx
src/app/submit/page.tsx
src/app/submit/confirmation/page.tsx
src/app/data-bank/page.tsx
src/app/guide/page.tsx
src/app/about/page.tsx
src/app/privacy/page.tsx
src/app/terms/page.tsx
src/app/admin/layout.tsx
src/app/admin/page.tsx
src/app/admin/reports/page.tsx
src/app/admin/reports/[id]/page.tsx
src/app/api/reports/route.ts
src/app/api/reports/[slug]/route.ts
src/app/api/stats/route.ts
src/app/api/map/reports/route.ts
src/app/api/admin/reports/route.ts
src/app/api/admin/reports/[id]/route.ts
src/components/layout/Header.tsx
src/components/layout/Footer.tsx
src/components/home/Hero.tsx
src/components/home/HomeStats.tsx
src/components/map/TrailSummaryMap.tsx
src/components/map/FullTrailMap.tsx
src/components/map/DemoToggle.tsx
src/components/reports/ReportCard.tsx
src/components/reports/ReportFilters.tsx
src/components/reports/ReportMetadata.tsx
src/components/submit/ReportForm.tsx
src/components/submit/MediaUploadField.tsx
src/components/ui/Button.tsx
src/components/ui/Card.tsx
src/components/ui/Badge.tsx
src/components/ui/StatCard.tsx
src/lib/db/prisma.ts
src/lib/reports/repository.ts
src/lib/reports/schemas.ts
src/lib/reports/formatters.ts
src/lib/map/at-route-simplified.geojson
src/lib/map/marker-utils.ts
src/lib/media/upload.ts
src/lib/media/exif.ts
src/lib/stats/stats.ts
src/lib/auth/admin.ts
db/seeds/categories.sql
db/seeds/trail_sections.sql
db/seeds/demo_reports.sql
db/seed.ts
tests/unit/report-schemas.test.ts
tests/unit/report-formatters.test.ts
tests/integration/reports-api.test.ts
tests/integration/media-upload.test.ts
tests/e2e/home.spec.ts
tests/e2e/submit-report.spec.ts
tests/e2e/admin-moderation.spec.ts

13. Testing and Validation Strategy

13.1 Unit Tests

Cover:

Zod validation for report submission.
Public DTO sanitization.
Date precision formatting.
Location privacy formatting.
Stats calculations.
Demo toggle filtering for stats, lists, and map markers.
Media upload validation for accepted file types and size limits.
Category/status label formatting.

13.2 Integration Tests

Cover:

GET /api/reports returns public-safe reports: public_unverified, verified_researched, and explained.
GET /api/reports filters by state/category.
GET /api/stats matches seeded reports and respects demo visibility.
POST /api/reports creates a non-public submission.
POST /api/reports accepts MVP media upload metadata only after file validation.
Admin endpoint rejects non-admin requests.
Admin endpoint permits moderator updates.

13.3 End-to-End Tests

Cover:

Visitor opens home page, sees map/stats/latest reports.

Visitor clicks a map marker and opens a report detail page.

Visitor filters reports by category.

Visitor submits a valid report and sees confirmation.

Visitor can submit a valid report with media and sees confirmation.

Admin logs in and approves a report for public viewing as `Not Verified Yet`.

Initially checked report appears publicly with an unverified flag.

Demo reports are hidden by default in production-mode tests and appear when the demo toggle is enabled.

13.4 Manual QA Checklist

Mobile home page usable at 375px width.
Map controls accessible with keyboard where feasible.
Form errors are screen-reader friendly.
Application/API responses for public views never expose exact private event/report coordinates.
Submission tests verify the form requires event/report GPS coordinates and labels them clearly as the location where the event happened, not where the report is being filed from.
Demo reports are clearly labeled as demo content.
Demo reports are hidden by default in production public views unless the toggle is enabled.
MVP media uploads reject unsupported or oversized files.
Report pages include appropriate disclaimers.
The site does not imply verification beyond moderation labels.

14. Privacy, Safety, and Legal Considerations

14.1 Location Privacy

Risks:

Exact campsite/shelter locations could expose individuals or sensitive areas.
Rare wildlife or protected locations should not be overexposed.
Submitters may accidentally upload EXIF GPS metadata.

Required controls:

Separate private and public coordinates.
Public coordinate fuzzing for sensitive reports.
EXIF stripping for images before public display.
Public location precision setting.
Moderator redaction before initial public approval.

14.2 Submitter Privacy

Required controls:

Email/contact never public by default.
Anonymous submission display option.
Trail name option.
Data deletion/contact request process.
Clear privacy policy.

14.3 Content Moderation

Reject or redact:

Personal attacks or doxxing.
Emergency claims requiring immediate intervention.
Instructions encouraging unsafe hiking behavior.
Hoaxes/jokes.
Copyrighted media without permission.
Exact location of sensitive resources if harmful.

14.4 Disclaimers

Every report detail page should include language like:

This is a submitted field report. WhiteBlazeFieldReports.com archives witness accounts and moderator notes but does not certify that an event occurred as described.

15. Launch Content

15.1 Required Copy Before MVP Launch

Homepage headline and subtitle.
About/mission page.
Submission guidance.
Common explanations guide.
Moderation policy.
Privacy policy.
Terms of use.
Demo data disclaimer.

15.2 SEO Basics

Target descriptive terms without overstuffing:

Appalachian Trail unusual sightings
Appalachian Trail field reports
strange lights Appalachian Trail
Appalachian Trail unexplained sounds
trail encounter reports

Each report page should include:

Unique title.
Short meta description.
State/trail section/category metadata.
Open Graph card.

16. Analytics and Metrics

16.1 Product Metrics

Home page views.
Map interactions.
Report detail views.
Submission starts.
Submission completions.
Filter usage.
Admin review time.

16.2 Quality Metrics

Spam submission rate.
Rejection rate.
Reports needing follow-up.
Reports with sufficient location/date detail.
Reports with media.

Use privacy-friendly analytics. Do not track precise user location beyond report submission data intentionally provided by the submitter.

17. Risks and Tradeoffs

17.1 Risk: Hoaxes and Low-Quality Reports

Mitigation:

Moderation queue before publication.
Hoax warning in submit flow.
Rate limiting and honeypot.
Quality labels and insufficient-detail status.

17.2 Risk: Privacy Leakage

Mitigation:

Public/private coordinate split.
DTO sanitization tests.
EXIF stripping.
Moderation redaction workflow.
Required GPS coordinates must represent the event/report location; do not infer, store, or publish the submitter’s current/reporting location unless they explicitly mark it as the event location.

17.3 Risk: Map Complexity Delays MVP

Mitigation:

Use simplified route GeoJSON first.
Avoid exact trail-mile calculations until after MVP.
Use approximate public markers.

17.4 Risk: Tone Becomes Too Sensational

Mitigation:

Use neutral copy.
Emphasize reports/accounts, not proof.
Add common explanations guide.
Use review labels.

17.5 Risk: Empty Real Database at Launch

Mitigation:

Include clearly labeled demo reports.
Add call-to-action for first real submissions.
Make demo mode visually obvious.

18. Open Questions

Answered: Accept reports from anywhere. Every submission must require GPS coordinates for the event/report location, not the submitter’s current/reporting location. AT proximity should be calculated and stored separately for filtering and display.

Answered: Do not require email verification for public submissions.

Answered: Allow media uploads in the MVP.

Answered: Use MapLibre GL with polished terrain/topographic vector styling because it should look best for end users; keep Leaflet as a fallback only if tile/provider constraints require it.

Answered: Do not build a public API or bulk download/export feature.

Answered: Do not build a public comment section at this time.

Answered: After an initial moderator check, allow public viewing even before verification/research. Publicly flag those reports as `Not Verified Yet` / `Public Unverified`.

Answered: Build a demo toggle. Demo data should be hidden by default in production and shown only when toggled on.

Answered: Do not build an offline/PWA drafts system for MVP.

Answered: Treat `WhiteBlazeFieldReports.com` as a serious research archive.

19. Recommended MVP Build Order

Project scaffold and CI.

Brand shell and static pages.

Database schema and demo seeds.

Application report APIs.

Home page with summary map and stats.

Reports list/detail pages.

Submit form and moderation queue.

Full map and data-bank indexes.

Guide/policy/trust copy.

QA/deployment.

This order ensures the first visible milestone is compelling: a map-first home page with demo reports and stats. Submission and moderation then make the product functional rather than just a showcase.

20. Definition of Done for First MVP

The MVP is complete when:

The home page shows a branded WhiteBlazeFieldReports.com experience for a serious research archive.
The summarized Appalachian Trail map uses MapLibre GL with polished terrain/topographic styling and displays public report markers.
Quick stats reflect public report data and respect the demo toggle.
Visitors can browse reports and open report detail pages.
Visitors can submit a new report with validation, required event GPS coordinates, privacy controls, and MVP media uploads.
Submitted reports are not automatically public; after initial moderator check they can become public as Not Verified Yet / Public Unverified.
Email verification is not required for report submission.
An admin can review, approve for public unverified viewing, later update verification/research labels, reject, or archive submissions.
Demo reports are clearly labeled and hidden by default in production unless the demo toggle is enabled.
Application APIs and pages do not leak private contact or exact private location data and do not provide public bulk download/export features.
No public comments and no offline/PWA drafts are included in MVP.
Lint, unit tests, integration tests, e2e smoke tests, and production build pass.
The site is built and, when a release is requested, delivered to /home/mgaif-test1/htdocs/test1.mgaif.com for the existing nginx/reverse-proxy test environment.

21. Immediate Next Step

When ready to implement, begin with Milestone 0: Project Foundation. Use TDD for validation, API, and privacy-sensitive code. Commit after each small completed task, and verify with npm run lint, npm run test, and npm run build before moving to the next milestone.

WB Plan

WhiteBlazeFieldReports.com Implementation Plan

Release/Test Delivery Target

1. Product Definition

1.1 Site Concept

1.2 Core User Groups

Casual visitors

Hikers / witnesses

Moderators / researchers

Trail researchers / enthusiasts

1.3 Content Scope

2. Inspiration From Similar Reporting Systems

2.1 NUFORC-style UFO Reporting

2.2 BFRO-style Encounter Reporting

2.3 Citizen-Science Observation Sites

3. Visual and UX Design Direction

3.1 Brand Positioning

3.2 Visual Style

3.3 Home Page Layout

Header / nav

Hero section

Summary map panel

Quick stats row

Featured / latest reports

Report categories strip

How reporting works

Footer

4. Information Architecture

4.1 Public Pages

4.2 Admin Pages

4.3 Application API Endpoints

5. Core Data Model

5.1 reports

5.2 phenomenon_categories

5.3 trail_sections

5.4 media_assets

5.5 moderation_events

5.6 admin_users

5.7 admin_sessions / Auth.js tables

5.8 MySQL implementation notes

6. New Report Submission Flow

6.1 Form Sections

Before you begin

What happened?

When did it happen?

Where did it happen?

Conditions

Media

Contact and privacy

Review and submit

6.2 Post-Submit UX

7. Map Design

7.1 Home Page Summary Map

7.2 Full Map Page

7.3 AT Geo Data Strategy

Chosen for MVP: Use MapLibre GL with a polished terrain/topographic vector style and a simplified AT GeoJSON line. This is the best-looking end-user option while remaining practical.

Fallback: If vector tile cost/API-key constraints become a problem, use Leaflet with high-quality raster terrain tiles.

Later: Store full route geometry using MySQL spatial columns/functions or precomputed route-segment tables and calculate nearest trail mile.

8. Demo Reports for MVP

8.1 Demo Report Set

Blue Ridge Lights Above Blood Mountain

Three-Part Whistle Near Standing Indian

Orange Glow Over Max Patch

Footsteps Circling Camp at Roan Highlands

Dark Figure at Grayson Highlands

Metallic Hum Near Shenandoah Wayside

Trackway After Rain Near Pine Grove Furnace

White Light Moving Along Kittatinny Ridge

Lost Time on Bear Mountain Descent

Mist Column Near Mount Greylock

Knocking Sounds in the Whites

Distant Blue Flashes Below Katahdin

8.2 Demo Data Requirements

8.3 Demo Toggle Requirements

9. First MVP Definition

9.1 MVP Goal

9.2 MVP Must-Haves

Branded responsive site shell.

Home page with hero, AT summary map, stats, and latest reports.

Public reports list with filtering by category/state.

5.1 `reports`

5.2 `phenomenon_categories`

5.3 `trail_sections`

5.4 `media_assets`

5.5 `moderation_events`

5.6 `admin_users`

5.7 `admin_sessions` / Auth.js tables

Create database migration for `phenomenon_categories`.

Create migration for `trail_sections`.

Create migration for `reports`.

Create migration for `media_assets`.

Create migration for `moderation_events`.

Implement `GET /api/reports` with pagination and filters.

Implement `GET /api/reports/[slug]`.

Implement `GET /api/stats`.

Implement `GET /api/map/reports`.

Build `TrailSummaryMap` component.

Build form route `/submit`.