Mapperk Specification

Home / Mapperk / Mapperk Specification

Mapperk

Your Local Deals, Smarter.

Overview

Mapperk is an open-source, location-aware business directory and promotions platform designed to connect consumers with verified businesses offering discounts, sales, promotional codes, special offers, and exclusive deals. The platform combines searchable business listings, product and service discovery, interactive maps, and promotion management to make local commerce more accessible and effective.

Mapperk enables verified business owners to manage their profiles, publish and schedule promotions, showcase products and services, reach relevant audiences, and measure engagement without surrendering control of their offers to a third-party deal marketplace. Consumers can discover promotions by business name, product type, category, keyword, or geographic location.

The platform follows a modular architecture with comprehensive core modules and optional plugin modules. It is designed for extensibility, privacy, accessibility, self-hosting, and community-driven development.

Project Goals

Connect consumers with verified businesses and relevant promotional offers.
Make local discounts and special offers easy to discover through search and interactive maps.
Give businesses direct control over their profiles, promotions, campaign schedules, and redemption policies.
Provide useful marketing and performance insights without requiring expensive third-party marketplace arrangements.
Support businesses of different sizes, industries, and geographic reach.
Enable local businesses to compete for visibility through relevant offers and transparent promotion options.
Provide a modular, extensible platform that can be customized for different communities and markets.
Support open-source development, self-hosting, data portability, and vendor-neutral integrations.
Protect business and customer data through privacy-conscious design and appropriate security controls.

Core Modules

Business Registration and Verification

Provide secure business owner registration and authentication.
Verify business email addresses and phone numbers.
Support business identity verification using appropriate documentation and authorized verification services.
Support sole proprietors, independent professionals, home-based businesses, franchises, nonprofits, and multi-location organizations.
Allow businesses to claim existing directory profiles and establish ownership.
Detect duplicate business registrations and suspicious ownership claims.
Provide verification badges with clearly defined verification levels.
Support verification review, expiration, renewal, suspension, and appeals.
Allow multiple authorized users to manage a business account.
Provide role-based permissions for owners, managers, marketing staff, and employees.
Maintain verification history and administrative audit records.
Protect businesses against unauthorized profile changes and account takeovers.

Business Profiles and Directory Listings

Provide customizable business profiles with names, logos, cover images, descriptions, and contact information.
Support physical addresses, geographic coordinates, service areas, and multiple business locations.
Display operating hours, holiday schedules, temporary closures, and location-specific information.
Organize businesses using searchable categories, subcategories, specialties, and keywords.
Support product and service catalogs with descriptions, images, prices, and availability.
Allow businesses to link to websites, online stores, booking services, and social media profiles.
Display accessibility information, parking details, delivery options, and accepted payment methods where provided.
Support business announcements, seasonal information, and company updates.
Provide customizable public profile URLs and shareable business links.
Generate QR codes that link directly to business profiles.
Display verification status and distinguish verified information from unverified claims.
Support business profile previews and controlled publishing workflows.
Optimize public profiles for search engine discovery and social sharing.

Promotion and Offer Management

Allow verified businesses to publish discounts, sales, special offers, and promotional codes.
Support percentage discounts, fixed-amount discounts, buy-one-get-one offers, bundles, and volume discounts.
Support clearance sales, seasonal promotions, flash sales, and limited-time offers.
Support free products, complimentary services, purchase bonuses, and loyalty incentives.
Support first-time customer offers, returning customer discounts, and membership promotions.
Support free delivery, discounted shipping, pickup incentives, and service packages.
Support restaurant specials, appointment offers, event promotions, and industry-specific deals.
Allow businesses to create online-only, in-store, or combined redemption offers.
Provide fields for offer descriptions, images, original prices, discounted prices, savings, promo codes, and redemption instructions.
Allow businesses to define eligibility conditions, exclusions, minimum purchases, and other restrictions.
Support start dates, expiration dates, publication schedules, and recurring promotions.
Allow businesses to pause, resume, edit, duplicate, cancel, and archive promotions.
Automatically remove expired offers from active search results.
Support quantity limits, redemption caps, and customer-specific usage restrictions.
Clearly communicate promotion terms to prevent misleading or ambiguous offers.
Maintain promotion history and track significant changes.

Search and Discovery

Support searches by business name, product, service, brand, category, keyword, and promotional code.
Support location-based searches using city, ZIP code, neighborhood, address, and geographic radius.
Allow users to choose a location manually or share their location with permission.
Provide filters for distance, category, discount type, price, expiration, and business verification.
Support filters for online offers, in-store deals, delivery, pickup, and appointment-based services.
Allow sorting by relevance, distance, newest offers, highest discount, price, and popularity.
Provide search suggestions, autocomplete, spelling correction, and relevant keyword matching.
Support searches within individual business profiles and specific business locations.
Allow users to save searches and receive alerts for newly matching offers.
Suppress expired, duplicate, and otherwise ineligible listings from active results.
Provide clear indicators for sponsored placements and other paid visibility options.
Support accessible list-based results as an alternative to map-based discovery.
Provide search engine-friendly public pages for businesses, categories, products, locations, and promotions.
Track aggregate search activity to identify popular categories and unmet customer demand.

Interactive Maps and Geographic Discovery

Display participating businesses and active promotions on an interactive map.
Support map markers, clustering, and geographic filtering.
Allow users to explore deals by neighborhood, city, ZIP code, or selected radius.
Provide map and list views with synchronized search results.
Display business locations, service areas, and relevant promotion information.
Support directions through compatible mapping services.
Display distance and estimated travel information when supported by the selected provider.
Distinguish physical storefronts from mobile businesses and service-area providers.
Allow users to save preferred locations and geographic search areas.
Support optional geographic summaries of promotion availability.
Provide privacy controls for location access and retention.
Allow self-hosted deployments to configure their preferred mapping and geocoding providers.

Customer Accounts and Personalization

Allow consumers to browse public listings without creating an account.
Provide optional customer accounts for saving deals and personalizing discovery.
Allow users to bookmark promotions and follow favorite businesses.
Support saved categories, preferred locations, and search preferences.
Provide recently viewed offers and saved promotional codes.
Allow users to receive alerts for new deals from followed businesses.
Provide configurable reminders for saved offers approaching expiration.
Support personalized discovery based on user-selected interests and preferences.
Allow users to control personalization, notification frequency, and data retention.
Provide account data export and deletion capabilities.
Support optional synchronization of saved items across devices.
Avoid requiring precise location access or unnecessary personal information to use essential features.

Coupon Redemption and Validation

Support digital coupons, QR codes, barcodes, and printable offers.
Generate unique coupon identifiers and optional single-use promotional codes.
Provide business-facing tools for validating coupons and confirming redemptions.
Enforce applicable expiration dates, eligibility requirements, and redemption limits.
Support manual redemption workflows for businesses without compatible scanners or point-of-sale systems.
Prevent duplicate redemption when the selected validation method supports reliable enforcement.
Provide clear redemption instructions for online and in-person offers.
Support redemption tracking by promotion, location, and date.
Distinguish promotion views, coupon saves, code copies, and confirmed redemptions.
Support offline-tolerant workflows where practical, with safeguards against conflicting redemption records.
Provide redemption history and exportable reports.
Support optional integrations with external point-of-sale and commerce systems.

Business Dashboard and Analytics

Provide a centralized dashboard for managing business profiles, locations, products, and promotions.
Display promotion impressions, listing views, clicks, shares, saves, and confirmed redemptions where available.
Provide campaign comparisons and historical performance reports.
Track aggregate search terms and referral sources where supported.
Display performance by business location, promotion category, and campaign period.
Provide reports on promotion expiration, active campaigns, and scheduled publications.
Support data exports in common formats.
Provide configurable reporting periods and scheduled summaries.
Allow access to analytics according to user roles and permissions.
Distinguish estimated engagement from verified transactions and actual sales.
Provide optional aggregate benchmarks when sufficient data exists and privacy requirements are met.
Offer actionable insights into campaign performance without automatically changing business pricing or promotion rules.

Customer Engagement and Sharing

Allow users to share business profiles and promotions through direct links, email, and compatible social platforms.
Provide copyable promotion URLs and promotional codes.
Support business announcements and profile updates.
Provide optional customer inquiry forms and contact links.
Support links to external reservations, appointment systems, and online stores.
Allow businesses to respond to eligible customer questions and feedback.
Provide reporting tools for spam, fraudulent offers, misleading claims, and inappropriate content.
Support optional reviews and feedback with clear moderation policies.
Distinguish verified redemptions or purchases from unverified customer feedback when supported.
Protect customers and businesses against harassment, spam, and abusive communication.

Notifications and Alerts

Support configurable email, web push, and compatible mobile push notifications.
Notify users about new promotions matching saved searches and selected interests.
Support alerts for followed businesses, saved deals, and approaching expiration dates.
Allow businesses to receive notifications about inquiries, campaign status, and redemption activity.
Provide configurable notification templates and delivery preferences.
Respect user consent, unsubscribe requests, and notification frequency limits.
Apply rate limits and abuse prevention to promotional messaging.
Track notification delivery and engagement where supported.
Avoid disclosing private user activity to businesses without an appropriate basis and user consent.

Business Administration and Moderation

Provide administrative tools for managing accounts, businesses, promotions, and platform settings.
Support business verification review and ownership dispute resolution.
Provide moderation queues for reported or potentially misleading promotions.
Allow administrators to suspend, restrict, or reinstate accounts under documented policies.
Maintain audit logs for consequential administrative actions.
Support user reports, business appeals, and documented enforcement decisions.
Detect duplicate listings, suspicious promotional activity, and potential abuse.
Provide configurable content policies and moderation rules.
Support delegated moderation for regional operators where appropriate.
Maintain transparent procedures for handling complaints and disputed listings.

Security and Privacy

Provide secure authentication, session management, and optional multi-factor authentication.
Enforce role-based access control and least-privilege permissions.
Protect data in transit and stored data using appropriate security measures.
Apply rate limits and protections against automated abuse.
Secure administrative actions and sensitive account changes.
Maintain appropriate security event logs and audit trails.
Minimize the collection of personal information and precise location data.
Provide configurable data retention and deletion policies.
Separate public business information from private customer account data.
Support secure backups, restoration procedures, and documented recovery practices.
Provide vulnerability reporting and a process for addressing security issues.
Ensure optional integrations receive only the permissions and data they require.
Document privacy implications and data handling practices for operators.

API and Integration Framework

Provide documented APIs for business profiles, locations, products, promotions, and search.
Support authorized business management through authenticated endpoints.
Provide webhook events for promotion publication, expiration, and redemption where applicable.
Support scoped API credentials, rate limits, and access monitoring.
Provide versioning and compatibility policies for public interfaces.
Support data import and export through documented formats.
Allow optional integrations with external business services.
Provide extension points for plugin modules and custom workflows.
Support integration health monitoring and error reporting.
Preserve data portability and allow operators to control which integrations are enabled.

Optional Plugin Modules

AI-Assisted Marketing

Generate draft promotion titles, descriptions, and marketing copy.
Suggest relevant categories, keywords, and search terms.
Help businesses improve offer clarity and calls to action.
Generate social media drafts and promotional campaign variations.
Translate promotional content into selected languages.
Generate image descriptions and accessibility text.
Summarize promotion performance and suggest potential improvements.
Recommend related products, services, and offers to interested customers.
Identify potential duplicate, suspicious, or misleading listings for human review.
Support locally hosted models and configurable AI providers.
Require business approval before publishing generated content or changing consequential campaign settings.

Loyalty and Rewards

Support digital punch cards, visit counts, and repeat-purchase rewards.
Allow businesses to configure loyalty points and membership tiers.
Provide customer-specific rewards and eligible redemption rules.
Support referral incentives and qualifying purchase rewards.
Allow businesses to define reward expiration and program terms.
Provide loyalty program reporting and abuse prevention.
Support optional cross-business reward partnerships.

Booking and Appointments

Support appointment request forms and external booking links.
Allow businesses to advertise appointment-specific discounts.
Provide links to supported reservation and scheduling systems.
Support booking reminders through compatible integrations.
Display availability when reliable information is provided by the connected service.
Allow businesses to configure booking terms and cancellation policies.
Keep payment processing optional and separate from the core directory.

E-Commerce and Point-of-Sale Integrations

Synchronize supported product catalogs and inventory information.
Connect promotional codes with compatible online stores.
Support point-of-sale coupon validation.
Import product feeds and business information.
Connect to external order and purchase confirmation systems.
Provide configurable webhooks and integration credentials.
Support sales attribution where the external provider permits it.
Keep integrations optional and avoid requiring a single commerce provider.

Events and Community Discovery

Allow businesses and approved organizers to publish events.
Support event-specific discounts and promotional codes.
Display event dates, locations, schedules, and registration links.
Support workshops, classes, markets, festivals, and community activities.
Provide event search and map discovery.
Support recurring events and seasonal campaigns.
Link event listings to participating business profiles and related offers.
Integrate with external ticketing and registration platforms where available.

Multi-Location and Franchise Management

Provide centralized management for businesses with multiple branches.
Allow shared or location-specific profiles and promotions.
Support centralized campaign templates and approval workflows.
Provide location-specific staff permissions.
Allow regional campaign scheduling and bulk publishing.
Provide consolidated reporting and branch-level analytics.
Support location-specific verification and ownership management.
Allow businesses to import and export location data.

Business Collaboration and Cross-Promotion

Allow complementary businesses to create joint promotional campaigns.
Support bundled offers and cross-referral programs.
Provide opt-in partnership requests and collaboration management.
Allow campaign-specific attribution for participating businesses.
Define responsibility for promotion terms, redemption, and customer service.
Support shared campaign pages and partner business discovery.
Keep participation voluntary and permissions explicit.

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/mapperk/

License & Notice Requirements

Mapperk 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.
Mapperk is free to use, modify, and distribute under the AGPL-3.0+ license, provided the applicable attribution requirements are maintained.
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 providing access to the corresponding source code of modified versions when required by the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – Mapperk

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 Mapperk. Developed the project concept for an open-source, location-based promotions directory that connects consumers with verified businesses offering discounts, sales, promotional codes, and exclusive deals through searchable listings and interactive maps.
Add other contributors here – [Date]
[Describe contribution in one sentence]

License – Mapperk

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.

Open Arsenal