Mapilio Backend

Mapilio is a street-level imagery platform for collecting, processing, and publishing geospatial imagery and detected street inventory. Its imagery and mapping integrations are designed to support open mapping workflows, including OpenStreetMap contributors, without implying endorsement by the OpenStreetMap Foundation.

This repository is the modern Laravel backend. It preserves API behavior required by existing web and mobile clients while replacing the legacy PyroCMS internals with explicit Mapilio domains, versioned APIs, and testable service boundaries.

Important

Modernization is active and there is no stable public release yet. External side effects such as AI dispatch, GeoServer publication, address enrichment, and UKM scoring remain disabled by default until their staging gates pass. The replacement operator dashboard is not implemented yet.

Responsibilities

The backend owns:

• public, mobile, web, and compatibility API contracts;
• identity and access boundaries used by those APIs;
• imagery and sequence metadata, not image bytes;
• AI dispatch, signed callback receipt, canonical detection, and publication intent;
• canonical PostgreSQL/PostGIS records and versioned geospatial projections;
• operational safety gates for queues, backups, migrations, and releases.

Image storage and delivery, face and license-plate anonymization, AI inference, and GeoServer remain separate services. See the ecosystem architecture for data flow and ownership boundaries.

Architecture

flowchart LR
    subgraph clients[Clients and community]
        web[Web platform]
        mobile[Mobile apps]
        kit[mapilio-kit]
        osm[Open mapping workflows]
    end

    backend[Mapilio Laravel backend]
    database[(PostgreSQL and PostGIS)]
    queue[(Queue and cache)]
    images[Image server and cache]
    nas[(TrueNAS imagery storage)]
    anonymizer[Anonymizer]
    ai[AI inference service]
    geo[GeoServer]

    web -->|Versioned and compatibility APIs| backend
    mobile -->|Auth, metadata, uploads, profiles| backend
    kit -->|Upload metadata| backend
    osm -->|Public imagery and map contracts| backend
    mobile -->|Image bytes| images
    kit -->|Chunked image archives| images
    backend --> database
    backend --> queue
    backend -->|Prediction request| ai
    ai -->|Signed result callback| backend
    backend -->|Image URLs| web
    backend -->|Image URLs| mobile
    images -->|Original and cached images| nas
    anonymizer -->|Blur in controlled storage workflow| nas
    geo -->|Versioned spatial projection| database
    backend -.->|Delivery disabled| geo

Loading

The legacy database remains a migration source while compatibility routes are retired incrementally. Public behavior may be preserved; PyroCMS modules and generated table structures are not.

Technology

• PHP 8.2 and Laravel 12
• PostgreSQL 14 with PostGIS for the target production schema
• SQLite for the safe local contributor workflow
• queues for prediction, enrichment, scoring, and publication work
• OpenAPI 3.1 for the modern /api/v1 contract
• Vite for the small Laravel web asset surface

Quick Start

Requirements: PHP 8.2+, Composer 2.2+, Node.js 22.12+ within major 22 or Node 24.x (the current LTS contributor option), npm 10+, and the documented PHP extensions. Other Node majors are unsupported until deliberately added. See the platform matrix, then run the read-only doctor before installing anything:

scripts/development/doctor.sh

git clone git@github.com:mapilio/backend.git
cd backend
composer install
npm ci
cp .env.example .env
php artisan key:generate
touch database/database.sqlite

Set an absolute SQLite path and explicitly enable synthetic local fixtures in .env:

APP_ENV=local
DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/backend/database/database.sqlite
MAPILIO_LEGACY_DB_CONNECTION=sqlite
MAPILIO_DEMO_SEEDING_ENABLED=true

Create the disposable schema and start Laravel:

php artisan migrate:fresh --seed
php artisan serve

Useful local endpoints:

• health: http://127.0.0.1:8000/api/v1/system/health
• synthetic AI feature: http://127.0.0.1:8000/api/v1/geo/ai-features/900000001
• Synthetic local API cookbook for read-only checks and safe response summaries

The demo seeder creates no account, password, legacy table, or external-service record. It refuses to run outside local/testing SQLite. Read the full local setup and safety rules before changing database configuration.

API Contracts

• Generated API reference
• Modern OpenAPI 3.1 contract
• Synthetic local API cookbook
• Legacy compatibility policy
• Unsupported legacy surface guardrails
• Current implementation status

Existing unversioned routes are compatibility contracts, not a pattern for new development. New public behavior belongs under an explicit versioned namespace and requires tests plus an OpenAPI change.

Verification

Run the complete local repository gate before opening a pull request:

scripts/release/verify-local-readiness.sh

It checks locked dependency metadata and advisories, formatting, baseline-free level 6 static analysis across the application, database, and test code, bounded baseline-free level 7 analysis for promoted paths, Laravel configuration caching, the full test suite, OpenAPI, the production asset build, Git history/worktree secrets, and redacted public-content policy across the candidate tree and complete history. Gitleaks 8.30.1 is required locally.

Focused commands:

php artisan test
composer format:test
composer analyse
composer analyse:level-7
npm run lint:openapi
npm run validate:api-examples
npm run check:api-docs
npm run check:license-state
npm run check:markdown-links
npm run audit:public-content
npm run build

GitHub Actions additionally runs every migration against a digest-pinned disposable PostgreSQL 14/PostGIS service. The PostGIS migration gate can also be run with a local Docker daemon.

Contributing

Start with CONTRIBUTING.md, then use the structured issue templates. Do not attach credentials, access tokens, database exports, production logs, personal data, unblurred imagery, private coordinates, or infrastructure details to an issue or pull request.

Security vulnerabilities must follow SECURITY.md and must never be posted publicly. General usage and project questions follow SUPPORT.md.

Maintainers use the community issue triage policy. The initial issue catalog is a pre-public draft and does not authorize contribution work before the license and governance gates are complete.

Documentation

• Documentation index
• Project roadmap
• Ecosystem architecture
• Domain boundaries
• Target database schema
• Runtime and deployment
• Contributor platform matrix
• Release readiness
• Security incident response
• Public-content audit

Governance And License

Community behavior is defined in CODE_OF_CONDUCT.md. The repository is still private and its license has not been selected. Root Composer and npm metadata therefore identify this project as proprietary/unlicensed; those markers do not change the licenses of third-party dependencies. No open-source license is implied until the owners add a reviewed LICENSE file and update the guarded metadata; see the public-release decisions.