Home / SceneMap / SceneMap Specification
SceneMap
Smart Maps. Beautiful Profiles.
Overview
SceneMap is an open-source, AI-assisted business directory designed to make discovering local businesses visual, intuitive, and informative. Each business receives a dedicated, photo-rich profile featuring personalized descriptions, curated photographs, business information, and an adaptable layout. Geographic organization and intelligent search allow visitors to discover businesses by ZIP code, town, city, neighborhood, county, region, category, and natural-language queries.
SceneMap combines human-curated content with AI-assisted webpage generation, design recommendations, geographic discovery, and administrative analytics. Authorized uploaders retain control over profile content, photographs, personalized observations, and publication. Visitors can search, browse, explore maps, view profiles, and share listings without submitting public reviews, ratings, comments, or photographs.
The platform follows a modular architecture with extensible core modules and optional plugins. AI assists with content preparation, page design, search, and website architecture while preserving human oversight over published information and material changes.
Core Modules
Business Profile Management
- Create a dedicated webpage for every business.
- Maintain business names, categories, addresses, contact details, websites, operating hours, service areas, and other relevant information.
- Support personalized descriptions, observations, highlights, and recommendations written or approved by authorized uploaders.
- Provide configurable profile fields based on business category.
- Support profile drafts, previews, publication, editing, unpublishing, archiving, and restoration.
- Generate customizable, search-friendly profile URLs.
- Support multiple locations or branches belonging to the same business.
- Detect potential duplicate listings and conflicting business information.
- Track profile creation, publication, and modification history.
- Provide profile templates and reusable content sections.
- Support bulk creation and updates through structured data imports.
- Preserve the distinction between uploader-provided information, AI-generated suggestions, and externally verified information.
Uploader-Controlled Content
- Restrict profile creation and editing to authorized uploaders and administrators.
- Prevent public visitors from submitting reviews, ratings, comments, photographs, or other profile content.
- Allow uploaders to control descriptions, photographs, captions, featured content, and section ordering.
- Provide configurable permissions for owners, administrators, editors, photographers, and read-only analysts.
- Support approval workflows for collaborative content management.
- Require appropriate authorization before AI-generated changes are published.
- Maintain an audit trail of content changes and publication actions.
- Allow authorized users to lock approved profile sections against unintended modifications.
- Provide content correction, removal, and restoration workflows.
- Keep visitor interactions focused on discovery, viewing, navigation, and sharing.
Photo and Media Management
- Support multiple photographs per business profile.
- Provide drag-and-drop uploads and bulk media management.
- Generate optimized thumbnails and responsive image variants.
- Support image galleries, carousels, grids, hero images, and full-screen viewing.
- Allow uploaders to select featured photographs and customize gallery order.
- Provide image cropping, rotation, focal-point selection, and basic adjustments.
- Support editable captions, accessibility descriptions, and image metadata.
- Offer AI-generated caption and image-description suggestions for uploader approval.
- Recommend image placement and gallery arrangements based on available content.
- Detect potential duplicate photographs.
- Preserve original images when configured to do so.
- Track attribution, ownership, and licensing information for uploaded media.
- Support configurable storage, backup, retention, and deletion policies.
- Optimize image delivery through responsive sizing, caching, and lazy loading.
AI-Assisted Page Generation
- Generate proposed business profile layouts from structured information, uploader-written content, and uploaded photographs.
- Recommend page sections based on business category, available content, and geographic context.
- Generate alternative layout and design proposals.
- Suggest typography, color palettes, spacing, image placement, and visual hierarchy.
- Support natural-language instructions for modifying page layouts.
- Allow uploaders to request changes to individual sections or entire profiles.
- Generate reusable templates for similar businesses.
- Adapt page layouts to desktop, tablet, and mobile displays.
- Provide previews before publication.
- Support manual editing alongside AI-assisted design.
- Preserve approved design elements and locked sections.
- Maintain revision history and support rollback.
- Generate page titles, headings, metadata, and accessibility recommendations.
- Avoid inventing business details, services, facilities, or other factual claims.
- Keep AI-generated content editable and subject to human approval.
AI Architecture Assistant
- Recommend website navigation and information architecture.
- Organize businesses into geographic hierarchies and relevant categories.
- Suggest relationships between businesses, locations, categories, and curated collections.
- Identify duplicate categories, redundant pages, and incomplete geographic coverage.
- Recommend internal linking strategies.
- Suggest improvements to directory navigation as the collection grows.
- Identify opportunities to introduce new modules or optional plugins.
- Recommend performance, accessibility, and maintainability improvements.
- Generate implementation proposals and explain their expected effects.
- Require authorization before applying structural changes that affect published pages or site behavior.
Geographic Directory and Mapping
- Organize businesses by country, state, county, city, town, neighborhood, ZIP code, and region.
- Provide location-specific directory pages.
- Support geographic search by manually entered location.
- Support radius-based discovery around a specified address or location.
- Display business locations on interactive maps.
- Synchronize map markers with filtered search results.
- Open the corresponding business profile from a map marker.
- Support list, grid, gallery, and map browsing modes.
- Provide directions links for businesses with suitable location data.
- Support physical locations, multiple branches, and service-area businesses.
- Allow authorized administrators to correct geographic information and map placement.
- Handle incomplete or approximate location information appropriately.
- Support configurable geographic boundaries and location hierarchies.
- Allow visitors to search without granting access to their device location.
- Support alternative mapping providers through modular integrations.
Intelligent Search and Discovery
- Provide a site-wide search interface for visitors.
- Support business names, categories, keywords, addresses, ZIP codes, towns, cities, and natural-language queries.
- Combine full-text search with geographic filtering.
- Support category synonyms, partial names, and common spelling variations.
- Provide autocomplete and suggested searches.
- Offer spelling correction and related search suggestions.
- Support semantic search through optional AI integrations.
- Allow filtering by location, distance, category, tags, services, amenities, and available profile attributes.
- Support configurable sorting by distance, business name, recent updates, and other relevant criteria.
- Display active filters and allow individual filters to be removed.
- Provide useful alternatives when a search returns no results.
- Preserve search parameters when visitors navigate between results and profiles.
- Generate shareable URLs for search results and filtered listings.
- Support pagination or progressive loading for large result sets.
- Keep essential keyword and geographic search functional when external AI services are unavailable.
- Ensure that search results are based on actual directory records rather than invented AI responses.
Personalized Business Profiles
- Present business information in clear, visually engaging layouts.
- Support hero images, galleries, descriptions, contact information, location maps, and business categories.
- Provide optional sections for services, menus, amenities, facilities, and other category-specific information.
- Allow uploaders to customize section visibility, order, and presentation.
- Display curated highlights and personalized observations supplied or approved by the uploader.
- Recommend related businesses based on category, location, and relevant profile attributes.
- Link profiles to corresponding geographic and category pages.
- Support curated collections and themed local guides.
- Provide social sharing metadata and copyable profile links.
- Support printable profiles and optional QR codes.
- Maintain attractive layouts when information or photographs are limited.
- Exclude public reviews, public ratings, and visitor-submitted content.
Search Engine Optimization
- Generate descriptive, search-friendly URLs.
- Support editable page titles, meta descriptions, headings, and canonical URLs.
- Generate XML sitemaps for eligible published profiles and directory pages.
- Provide appropriate structured data based on verified business information.
- Support breadcrumbs and internal linking across locations and categories.
- Generate social sharing metadata and preview images.
- Support configurable indexing policies for drafts, archived pages, and incomplete listings.
- Provide redirects when published profile URLs change.
- Identify broken links, missing metadata, and duplicate pages.
- Support localized metadata and multilingual page discovery.
- Avoid automatically generating large numbers of thin or repetitive pages.
- Provide SEO audits and actionable improvement suggestions.
Administrative Dashboard
- Provide a centralized interface for managing businesses, profiles, media, categories, and locations.
- Display profile publication status and content completeness.
- Support bulk editing, importing, exporting, and archiving.
- Manage uploader permissions and administrative roles.
- Configure profile templates, geographic hierarchies, and category-specific fields.
- Review AI-generated content and pending publication changes.
- Identify potential duplicate records and outdated information.
- Configure search behavior, caching, and indexing policies.
- Monitor background tasks, application errors, and system health.
- Manage optional plugins and external integrations.
- Provide administrative audit logs and configuration history.
- Support backups, restoration, maintenance operations, and data migration.
Analytics and Reporting
- Track profile views and aggregate visitor engagement.
- Measure searches, search-result selections, and queries that return no results.
- Identify frequently viewed businesses, categories, and geographic areas.
- Measure clicks on external websites, phone links, and directions links.
- Analyze photo-gallery engagement where appropriate.
- Compare traffic trends over configurable periods.
- Monitor profile completeness and update activity.
- Provide filters for geographic area, business category, and date range.
- Support interactive charts, drill-down reports, and exportable datasets.
- Provide governed metrics with consistent definitions.
- Restrict administrative analytics to authorized users.
- Support optional integration with Lightdash for interactive business intelligence dashboards.
- Keep internal analytics separate from public business profile content.
- Apply privacy-conscious measurement, data minimization, and configurable retention policies.
Security and Privacy
- Require authentication for administrative and uploader functions.
- Apply role-based access controls and least-privilege permissions.
- Protect authenticated sessions and sensitive administrative operations.
- Validate and sanitize submitted content.
- Apply appropriate protections against common web application vulnerabilities.
- Validate uploaded files, restrict file sizes, and process images safely.
- Store credentials and API keys securely outside public client-side code.
- Restrict access to private media and administrative resources.
- Document the data sent to external AI and mapping services.
- Provide configurable data retention and deletion policies.
- Support privacy-conscious analytics and applicable consent requirements.
- Maintain audit records for sensitive changes.
- Provide content correction and takedown procedures.
- Ensure that visitors can browse public profiles without creating accounts.
- Keep core directory functions available when optional external services are unavailable.
Performance, Accessibility, and Reliability
- Provide responsive layouts across supported device sizes.
- Optimize image delivery and static assets.
- Cache frequently requested profiles and search results.
- Use appropriate indexes for geographic, categorical, and full-text queries.
- Support efficient pagination and large directory collections.
- Process expensive image and AI operations asynchronously where appropriate.
- Provide loading, empty, and error states.
- Follow established web accessibility guidelines.
- Support keyboard navigation, screen readers, readable contrast, and descriptive image text.
- Respect reduced-motion preferences.
- Monitor search latency, application errors, and background job failures.
- Provide automated tests for search, permissions, publishing, and profile rendering.
- Support database migrations, backup verification, and recovery procedures.
- Include deployment documentation and operational health checks.
Optional Plugin Modules
Advanced Mapping Plugin
- Provide additional map providers and configurable map styles.
- Support geographic boundary overlays and custom map layers.
- Add advanced radius search and geographic clustering.
- Support custom markers and map display preferences.
- Provide route and directions integrations.
- Allow administrators to configure provider credentials and usage limits.
AI Provider Plugin
- Support configurable hosted and local AI models.
- Provide AI-assisted content generation, captions, translations, and layout recommendations.
- Integrate optional embedding-based semantic search.
- Allow administrators to configure model selection, privacy settings, and usage limits.
- Support AI provider replacement without changing core profile functionality.
- Provide graceful fallbacks when AI services are unavailable.
Advanced Image Processing Plugin
- Provide additional image transformations and editing capabilities.
- Support advanced gallery layouts and image collections.
- Offer configurable image-processing pipelines.
- Support external image-processing services.
- Provide additional media metadata and provenance management.
Analytics and Lightdash Plugin
- Integrate directory data with Lightdash dashboards and governed metrics.
- Provide configurable reports for geographic coverage, profile engagement, and search performance.
- Support date filters, category filters, and geographic drill-downs.
- Enable scheduled reports and supported data exports.
- Restrict dashboards and underlying datasets according to administrative permissions.
Localization Plugin
- Support translated business descriptions and interface text.
- Provide language-aware search and navigation.
- Support localized page metadata and regional formatting.
- Allow uploaders to review translations before publication.
- Preserve original content alongside translated versions.
Import and Export Plugin
- Import business records and media references from supported formats.
- Provide field mapping, validation, and duplicate detection.
- Support bulk profile creation and updates.
- Export selected profiles and directory metadata.
- Generate import reports identifying errors and skipped records.
- Support migration from existing business directory platforms.
Promotion and Sharing Plugin
- Generate QR codes for business profiles and curated collections.
- Provide enhanced printable profiles and promotional materials.
- Support featured listings controlled by authorized administrators.
- Provide configurable sponsored placements with clear labeling.
- Support curated regional guides and shareable collections.
- Keep promotional features optional and separate from core search behavior.
Advanced Search Plugin
- Integrate dedicated search engines for larger directories.
- Support advanced faceted filtering and ranking configuration.
- Provide multilingual and semantic search enhancements.
- Support search synonyms and administrator-managed relevance rules.
- Offer additional search analytics and query diagnostics.
Integration Framework Plugin
- Provide extension points for external services and custom modules.
- Support documented APIs and event-driven integrations.
- Allow compatible plugins to add profile fields, search filters, administrative tools, and page components.
- Define plugin permissions and configuration boundaries.
- Support plugin compatibility checks and controlled activation or deactivation.
Specification Branding License (SBL)
Standard
- Fully AGPL-3.0+ compliant system
- Copyleft enforced for network deployments
- Required attribution:
- Roxanne Ardary
- https://www.roxanneardary.com/
Optional
- Specification Branding License (SBL)
- Attribution-free commercial deployment
- Pricing based on scale, usage, and deployment scope
- https://roxanneardary.com/scenemap/
License & Notice Requirements
SceneMap is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).
By contributing to any Open Arsenal project, you agree that your contributions will also be released under this license.
Please note the following:
- All contributions must comply with the AGPL-3.0+ terms.
- Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to Roxanne Ardary and roxanneardary.com.
- SceneMap specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
- The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update
notice.md. - When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
- Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.
For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.
Notice – SceneMap
Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.
Contributors
This file tracks contributors and their specific contributions to the project.
- Roxanne Ardary, roxanneardary.com – October 28, 2026
Created the repository for SceneMap. Conceived and designed an open-source, AI-assisted business directory featuring personalized, photo-rich business profiles, intelligent geographic search, interactive maps, AI-assisted webpage generation, and administrative analytics. - [Add other contributors here] – [Date]
[Describe contribution in one sentence]
License – SceneMap
This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).
Key Points:
- You are free to use, modify, and distribute the code.
- All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
- The software is provided “as is,” without warranty of any kind.
For the full license text, see GNU AGPL-3.0 License.



