Milestones
List view
# Public Device-Charging Map — Product Roadmap > Working title only. Product naming, domain selection, visual identity, and final messaging are development deliverables and have not yet been decided. ## Project status - **Stage:** Discovery and MVP planning - **Initial pilot:** One city or tightly defined service area - **Primary experience:** Mobile-first web application - **Authentication:** None for the MVP - **Development database:** SQLite - **Development data persistence:** Versioned GitHub checkpoints ## Vision Create a privacy-first, community-verified map that helps people find free and reliable places to charge phones and other essential devices. The product is designed for people who cannot depend on a private electrical outlet, including people experiencing homelessness, formerly incarcerated people navigating reentry, travelers, students, gig workers, and people affected by emergencies. ## Problem statement Phones are often necessary for shelter placement, employment, benefits, transportation, court obligations, medical care, navigation, and communication. People without reliable housing may have no dependable place to charge them. Existing map applications can locate businesses and electric-vehicle chargers, but they generally do not answer questions such as: - Is a regular electrical outlet or USB charger available? - Is charging free? - Is the outlet indoors or outdoors? - Is a purchase, membership, or identification required? - Is the location open and accessible now? - When was the location last successfully used? - Are seating, Wi-Fi, and wheelchair access available? ## Value proposition Help a person quickly identify the nearest practical charging option, understand its access conditions, and judge whether its information is still reliable. ## Product principles 1. **Useful before comprehensive:** A small number of accurate locations is more valuable than a large, unreliable dataset. 2. **Privacy by default:** Do not build movement histories or collect identities that the service does not need. 3. **No account required:** Core discovery, submission, and confirmation workflows remain available without registration. 4. **Transparent confidence:** Show why a location is considered verified, uncertain, outdated, or unavailable. 5. **Low-bandwidth first:** Optimize for older phones, limited data plans, intermittent connectivity, and small screens. 6. **Community maintained:** Combine open data, partner verification, and anonymous field reports. 7. **Accessible and respectful:** Avoid stigmatizing language and design for a broad public audience. ## MVP scope ### Included - Map and list views of nearby charging locations - One-time browser geolocation with a manual location-search alternative - Filters for access, hours, outlet type, cost, and selected amenities - Location detail pages - Anonymous location submissions - Anonymous working/unavailable reports - Duplicate-location detection - Confidence and freshness labels - Mobile-responsive, installable progressive web application - SQLite storage - Seed and development database checkpoints stored in GitHub - Basic input validation, abuse controls, and moderation status ### Not included - User accounts, login, profiles, roles, or authentication - Continuous background location tracking - Purchased mobile-location or data-broker feeds - Collection of device identifiers or personal movement history - Native iOS or Android applications - Payments, subscriptions, advertising, or rewards - Real-time outlet occupancy detection - Nationwide launch during the initial MVP - Automated publication of AI-generated or unverified locations ## Success criteria The pilot will be considered useful when it can demonstrate: - At least 25 verified charging locations in the pilot area - At least 80% of tested listings accurately describe current access - A nearby result can be reached within three interactions from the landing page - A new location can be submitted in under two minutes - A working/unavailable confirmation can be submitted in under 30 seconds - The primary map and location pages meet WCAG 2.2 AA targets - The core experience remains usable on a constrained mobile connection - No personal account or persistent visitor identity is required ## Proposed technical foundation | Concern | MVP choice | | --- | --- | | Application | Next.js with TypeScript | | Mapping | MapLibre GL with OpenStreetMap data | | Database | SQLite | | ORM and migrations | Drizzle ORM and Drizzle Kit | | SQLite driver | `better-sqlite3` | | Styling | Lightweight component and token system selected during branding | | Testing | Vitest and Playwright | | Deployment | Node-compatible host with a persistent volume | | Development persistence | GitHub-versioned database checkpoints and migrations | The technical choices may be adjusted during project setup if a dependency creates unnecessary deployment or accessibility constraints. ## Data strategy ### Initial sources 1. **Manual research and field verification** - Begin with libraries, community centers, public buildings, transit facilities, and participating organizations. - Do not mark a candidate as verified until someone confirms the charging access. 2. **OpenStreetMap** - Import relevant candidates such as `amenity=device_charging_station`. - Consider `socket:*`, `opening_hours`, `access`, and accessibility metadata when available. - Preserve required OpenStreetMap attribution. 3. **Public library and municipal datasets** - Use official locations and operating hours to identify candidate sites. - Treat these as candidates because the presence of a public facility does not prove that an outlet is available. 4. **Community reports** - Allow visitors and outreach workers to add, confirm, or report locations. - Keep structured reports short and avoid collecting personal information. ### Data confidence states | State | Meaning | | --- | --- | | `needs_confirmation` | Candidate location without recent field verification | | `recently_used` | At least one recent successful community confirmation | | `verified` | Confirmed by a trusted partner or multiple independent reports | | `possibly_outdated` | No successful confirmation within the freshness window | | `unavailable` | Recent evidence indicates that charging access is removed or blocked | Confidence rules must be documented and understandable. The application should never imply guaranteed access. ## Privacy and safety baseline - Request browser location only after a clear user action. - Use the location to calculate nearby results without creating a movement history. - Do not store a visitor's search location by default. - Do not collect names, email addresses, device identifiers, or account profiles. - Strip metadata from uploaded images before retaining them. - Reject executable markup and sanitize all user-supplied text. - Apply server-side validation and request-size limits. - Use short-lived, privacy-preserving rate-limit signals where necessary. - Publish a plain-language privacy notice before accepting public submissions. - Allow reports to flag a location as restricted, removed, or inappropriate to publish. - Avoid listing private residential outlets unless a formal, consent-based partner program is created after the MVP. ## SQLite and GitHub workflow The development database will live at: ```text data/charging-map.db ``` The database, schema migrations, and approved seed data may be committed to GitHub to preserve work between development sessions. SQLite temporary files must not be committed: ```gitignore data/*.db-shm data/*.db-wal data/*.db-journal ``` Before committing a database checkpoint, write pending WAL changes into the primary database: ```sql PRAGMA wal_checkpoint(TRUNCATE); ``` GitHub is a development checkpoint and backup mechanism, not the live application's runtime database. A deployed MVP that accepts submissions must use a persistent server volume. Runtime requests must not automatically commit directly to the repository. ## Core data entities ### Charging location - Stable identifier - Name and description - Latitude and longitude - Street address when appropriate - Location category - Indoor, outdoor, or mixed access - Public, customer, member, or restricted access - Free or purchase required - 24/7 status or opening hours - Wall outlet, USB-A, USB-C, or charging-locker availability - Seating, Wi-Fi, and wheelchair-accessibility indicators - Access notes and restrictions - Source and source URL - Confidence state - Confirmation and unavailable-report counts - Last verified timestamp - Created and updated timestamps ### Location report - Stable identifier - Related charging-location identifier - Report type - Optional short note - Moderation status - Creation timestamp Initial report types: - `working` - `unavailable` - `hours_changed` - `outlet_removed` - `access_restricted` - `duplicate` - `other` ## Delivery roadmap ### Phase 0 — Discovery and project definition - [ ] Select the initial pilot city or service boundary - [ ] Interview at least three potential users or frontline service providers - [ ] Document the most common charging-location scenarios - [ ] Identify the minimum information needed to decide whether a location is usable - [ ] Validate the problem statement without relying on an unsupported homelessness statistic - [ ] Define the pilot's location-verification standard - [ ] Identify at least two community or public-agency data partners - [ ] Record assumptions, open questions, and known risks **Exit condition:** The team can clearly describe the user, problem, smallest useful solution, and pilot boundary. ### Phase 1 — Repository and engineering foundation - [ ] Initialize the application and TypeScript configuration - [ ] Add linting, formatting, and type-checking commands - [ ] Configure Vitest and Playwright - [ ] Add environment-variable validation - [ ] Establish application, component, database, and test directories - [ ] Configure SQLite, Drizzle ORM, and migration scripts - [ ] Create the initial database schema and indexes - [ ] Add deterministic development seed data - [ ] Add SQLite checkpoint and backup scripts - [ ] Document local setup and contribution steps - [ ] Add continuous integration for lint, type-check, test, and build **Exit condition:** A new contributor can clone the repository, create the database, run the application, and execute the test suite from documented commands. ### Phase 2 — Branding and experience direction - [ ] Define the product's desired personality and public-service positioning - [ ] Generate and evaluate naming directions - [ ] Perform preliminary domain, repository-name, and trademark screening - [ ] Select a working product name and tagline - [ ] Establish respectful, non-stigmatizing content guidelines - [ ] Create accessible light and dark color palettes - [ ] Define typography, spacing, map-marker, status, and icon tokens - [ ] Produce a simple wordmark or project mark appropriate for the MVP - [ ] Test color contrast and common color-vision deficiencies - [ ] Apply the selected identity to repository documentation and interface copy **Exit condition:** The project has a usable working identity and accessible design tokens without delaying functional development. ### Phase 3 — Read-only map experience - [ ] Render the pilot area with MapLibre - [ ] Add OpenStreetMap attribution - [ ] Load charging locations from SQLite through a read-only API - [ ] Display differentiated markers for confidence states - [ ] Build synchronized map and list views - [ ] Add manual location search - [ ] Add optional one-time browser geolocation - [ ] Sort nearby results by distance - [ ] Add filters for open now, free access, outlet type, indoor/outdoor access, and accessibility - [ ] Build location detail pages - [ ] Display last-verified dates and clear access disclaimers - [ ] Provide meaningful loading, empty, offline, and error states **Exit condition:** A mobile visitor can find and understand nearby charging options without creating an account. ### Phase 4 — Anonymous submissions and confirmations - [ ] Create the add-location form - [ ] Add map-pin placement and coordinate validation - [ ] Create the working/unavailable confirmation flow - [ ] Add structured issue-report options - [ ] Validate all submissions on the server - [ ] Add geographic bounds for the pilot area - [ ] Detect likely duplicate locations by distance and normalized name - [ ] Add request-size and submission-frequency limits - [ ] Add a moderation state for new locations and sensitive changes - [ ] Prevent arbitrary HTML or executable content in notes - [ ] Add success, validation, and retry feedback - [ ] Test all submission flows without authentication or cookies **Exit condition:** Visitors can safely contribute useful information without an account, and low-confidence submissions do not silently become verified listings. ### Phase 5 — Confidence and data quality - [ ] Implement documented confidence-state rules - [ ] Recalculate status after relevant reports - [ ] Define freshness windows by location type - [ ] Show the evidence supporting a location's status - [ ] Add duplicate-review and merge tooling for development maintainers - [ ] Import selected OpenStreetMap candidate locations - [ ] Import selected public-library or municipal candidates - [ ] Preserve source attribution and update timestamps - [ ] Verify the first 25 pilot locations - [ ] Add database-integrity and invalid-coordinate checks **Exit condition:** At least 25 pilot locations have traceable sources and defensible confidence labels. ### Phase 6 — Accessibility, performance, and resilience - [ ] Complete keyboard-only navigation testing - [ ] Add screen-reader labels and non-map alternatives - [ ] Ensure status is never communicated by color alone - [ ] Meet WCAG 2.2 AA contrast targets - [ ] Respect reduced-motion settings - [ ] Set minimum touch-target sizes - [ ] Optimize the initial JavaScript and map payload - [ ] Add low-bandwidth behavior and cached application assets - [ ] Make the application installable as a PWA - [ ] Test location discovery when geolocation is denied - [ ] Test representative small screens and older mobile devices - [ ] Define a fallback experience when map tiles fail **Exit condition:** The core task remains usable with assistive technology, denied geolocation, a small screen, and a constrained connection. ### Phase 7 — Security and privacy review - [ ] Threat-model anonymous submission and file-upload surfaces - [ ] Verify SQL queries are parameterized - [ ] Add security headers and a restrictive content-security policy - [ ] Remove unnecessary request logging and sensitive query parameters - [ ] Strip image metadata or defer image uploads from the MVP - [ ] Confirm that searches do not create persistent location histories - [ ] Add retention rules for moderation and abuse-prevention data - [ ] Write a plain-language privacy notice - [ ] Write community submission and acceptable-use guidance - [ ] Test rate limits and malformed submissions - [ ] Confirm that no repository or deployment secrets reach the client **Exit condition:** The MVP has documented privacy behavior, tested abuse controls, and no unnecessary personal-data collection. ### Phase 8 — Pilot deployment and validation - [ ] Select a Node-compatible host with persistent SQLite storage - [ ] Configure database backups and a recovery test - [ ] Run production migrations during deployment - [ ] Verify that deployments do not overwrite live database changes - [ ] Add health and database-readiness checks - [ ] Conduct a field test with representative users - [ ] Validate a sample of listings in person - [ ] Record task completion, accuracy, and submission-time metrics - [ ] Collect qualitative feedback without requiring user accounts - [ ] Fix pilot-blocking accessibility and reliability issues - [ ] Publish known limitations and feedback instructions - [ ] Decide whether to continue, revise, or stop based on pilot evidence **Exit condition:** The pilot is available to its intended test community, its dataset survives deployment, and the team has evidence about whether it creates value. ## AI-assisted development plan AI may support the project by: - Drafting tests, migration plans, and implementation alternatives - Normalizing imported public-data fields - Suggesting possible duplicate listings for human review - Summarizing conflicting community reports - Producing accessible plain-language descriptions - Identifying missing test cases and documentation gaps AI must not: - Invent charging locations - Automatically mark a location as verified - Publish private or residential outlet locations without explicit consent - Infer a person's housing or incarceration status - Create or retain visitor movement profiles - Resolve conflicting safety or access reports without human review ## Testing strategy ### Unit tests - Confidence-state transitions - Distance calculations - Opening-hours and filter behavior - Input normalization and validation - Duplicate-candidate scoring - Database constraints and migrations ### Integration tests - Location read APIs - Anonymous submission APIs - Report creation and status recalculation - SQLite migrations against a clean database - Seed imports and source attribution - Rate-limit and invalid-input behavior ### End-to-end tests - Find the nearest charging location - Search manually after denying geolocation - Filter for free and currently accessible locations - Submit a new candidate location - Confirm that an outlet worked - Report that an outlet is unavailable - Complete core workflows using only a keyboard - Recover from offline and server-error states ### Field validation - Verify a representative sample of locations in person - Compare displayed hours and restrictions with observed conditions - Test the application using a low-cost mobile device - Ask pilot users to complete tasks without coaching ## Engineering workflow Each milestone should follow a small, reviewable cycle: 1. Open an issue describing the user problem and acceptance criteria. 2. Create a focused branch. 3. Implement the smallest complete change. 4. Add or update tests and documentation. 5. Run linting, type checks, tests, and the production build. 6. Review accessibility, privacy, and data implications. 7. Commit intentionally with a descriptive message. 8. Merge only when the acceptance criteria are demonstrably satisfied. At the end of sessions that change approved development data: 1. Checkpoint the SQLite WAL. 2. Validate database integrity. 3. Review which records changed. 4. Commit the primary database and relevant migrations together. 5. Never commit temporary SQLite files, secrets, or raw personal data. ## Definition of done A roadmap item is complete when: - Its acceptance criteria are satisfied - Relevant automated tests pass - User-facing behavior is keyboard accessible - Mobile and failure states have been considered - Database changes include a migration or documented seed update - Privacy and security implications have been reviewed - Documentation reflects the implemented behavior - No secrets, temporary database files, or unnecessary personal data are committed ## Risks and mitigations | Risk | Mitigation | | --- | --- | | Listings become outdated | Show verification dates, expire confidence, and make reporting fast | | Anonymous spam or vandalism | Validate, rate-limit, detect duplicates, and moderate low-confidence changes | | Public facility data implies outlets that do not exist | Label imported records as candidates until field-confirmed | | A listed outlet is private or restricted | Exclude residential locations and support rapid restriction reports | | Git conflicts corrupt the SQLite database | Use a single data-maintainer workflow, checkpoint before commits, and avoid parallel binary edits | | Deployment loses new submissions | Require persistent storage and verify restore procedures before pilot launch | | Map-centric design excludes users | Maintain an equivalent list view and manual search path | | Product language stigmatizes intended users | Include affected users and service providers in naming and content review | | Scope grows into a general resource directory | Keep the MVP centered on finding usable device-charging access | ## Post-MVP opportunities These ideas require evidence from the pilot before development: - Partner-managed location claims - Opt-in organization dashboards - Additional pilot cities - Downloadable offline location packs - Multilingual content - Public-data export or API - Consent-based power-partner network - Charging lockers and solar charging partnerships - Integration with broader reentry and homelessness resource directories - Native mobile applications Authentication should be reconsidered only if a validated post-MVP workflow cannot be supported safely without it. ## Immediate next actions - [ ] Select the pilot geography - [ ] Create the repository and issue templates - [ ] Complete three discovery interviews - [ ] Establish the first SQLite schema migration - [ ] Add five representative seed locations - [ ] Build the read-only mobile map prototype - [ ] Schedule branding and naming work alongside, not ahead of, functional validation ## Reference data sources - [OpenStreetMap device-charging-station tag](https://wiki.openstreetmap.org/wiki/Tag%3Aamenity%3Ddevice_charging_station) - [OpenStreetMap socket tags](https://wiki.openstreetmap.org/wiki/Key%3Asocket%3A%2A) - [Institute of Museum and Library Services Public Libraries Survey](https://www.imls.gov/research-evaluation/surveys/public-libraries-survey-pls) - [Prison Policy Initiative: Nowhere to Go](https://www.prisonpolicy.org/reports/housing.html) - [Vera Institute of Justice: No Access to Justice](https://www.vera.org/publications/no-access-to-justice-homelessness-and-jail)
No due date•8/13 issues closed