Plings Documentation

Created: Tue 29 Jul 2025 07:14:58 CEST
Updated: Wed 06 May 2026 17:14:18 CEST - Phase 1 naming migration: introduced Plings-Web/Plings-API/Plings-Gateway conventions; added native iOS/Android in architecture references; clarified scan transport-agnosticism (QR/NFC/RFID)
Document Version: 1.2 - Naming migration and multi-UI architecture references
Security Classification: Internal Technical Documentation
Target Audience: Developers, AI Agents, Technical Writers
Author: Paul Wisén

This README serves as the primary navigation point for AI agents and developers working with Plings documentation. It provides the complete structure overview and placement guidelines.

Live Documentation Site: https://docs.plings.io

Naming migration in progress: The Plings system uses these conceptual repository names: Plings-API (disk: Plings-API/), Plings-Gateway (disk: Plings-Gateway/), Plings-Web (disk: Plings-Web/), plus planned Plings-iOS and Plings-Android. Use the conceptual names in new documentation; reserve disk paths for actual file references. See the workspace CLAUDE.md for full context.

Directory Structure Overview

🏗️ Core Architecture

/architecture/
├── README.md                           # Architecture overview and principles
├── system-overview.md                  # HIGH-PRIORITY: Multi-service ecosystem, Gateway layer
├── database_architecture.md            # Dual database design (PostgreSQL + Neo4j)
├── technology-stack-decisions.md       # Technology choices and rationale
├── solana-payment-architecture.md      # Blockchain payment integration
└── api-security-guidelines.md          # Security best practices

🔧 Core Systems Documentation

/core-systems/
├── README.md                           # Core systems overview
├── s-plings-io/                        # Gateway service documentation (transport-agnostic: QR/NFC/RFID)
│   ├── README.md                       # Gateway overview (4 functions)
│   ├── url-structure.md               # URL parameters and routing
│   ├── verification-strategy.md       # Cached public key verification
│   └── routing-logic.md               # Intelligent routing rules
├── plings_identifier.md               # HD wallet identifier system
├── spatial-relationships.md           # Object location tracking  
├── ownership-handling.md              # Ownership and transfer logic
└── class-system.md                     # Object classification system

🌐 API Documentation

/api/
├── README.md                          # API overview and integration guide
├── api-endpoints.md                   # GraphQL schema and endpoints
├── authentication.md                 # Authentication flows
├── data-models.md                    # Core data structures
└── integration-examples.md           # Code examples and patterns

💾 Database Documentation

/database/
├── README.md                          # Database overview (⚠️ READ SCHEMA-VERIFICATION.md FIRST!)
├── SCHEMA-VERIFICATION.md             # 🚨 CRITICAL: Verified production schema
├── neo4j-core-schema.md              # Graph database schema
├── supabase-core-schema.md           # PostgreSQL schema (wallet-first)
├── migration-strategy.md             # Database migration procedures
└── predicate-catalogue.md            # Relationship types catalog

📋 Use Cases & Requirements

/use-cases/
├── overview.md                        # Use case index
├── workflow-create-object.md          # Object creation workflows
├── workflow-scan-to-pay.md           # Commerce scanning flows
├── workflow-lost-and-found.md        # Lost object recovery
└── requirements-analysis.md          # Business requirements

⚠️ IMPORTANT: Always check use cases before implementing features!

🎨 Frontend Documentation

/frontend/
├── README.md                          # Frontend architecture overview
├── component-architecture.md         # React component structure and patterns
├── state-management.md              # State management patterns
├── routing.md                        # Frontend routing system
└── admin/                            # Admin console documentation
    ├── README.md
    └── [admin-specific files]

🔧 Development Guides

/development/
├── README.md                          # Development setup overview
├── getting-started.md                # Quick start guide
├── api-integration.md               # Backend integration patterns
├── testing-strategy.md              # Testing approaches
└── deployment.md                    # Deployment procedures

🎨 Brand & Design

/brand/
├── design-system.md                  # Design system guidelines
├── implementation-guide.md          # Implementation patterns
├── requirements.md                  # Brand requirements
└── fonts/Poppins/                   # Font assets
    └── [Poppins font files]

🤖 Agent Workflow Guidelines

Documentation Placement Rules

Content Type	Primary Location	Secondary Location	Notes
New Features	`/use-cases/` first	Implementation in relevant system dir	Always document requirements first
System Architecture	`/architecture/`	Cross-reference in affected systems	Include impact analysis
API Changes	`/api/`	Update affected core systems	Maintain backwards compatibility docs
Database Changes	`/database/`	Update affected systems	Always update SCHEMA-VERIFICATION.md
Frontend Components	`/frontend/`	Include usage examples	Document props and state management
s.plings.io Gateway	`/core-systems/s-plings-io/`	Reference in architecture	Universal scan routing (QR/NFC/RFID)
Business Logic	`/core-systems/`	Cross-reference in API docs	Core system functionality

🔄 Agent Development Workflow

Start Here: Read this README.md for structure understanding
Check Use Cases: Review /use-cases/ before implementing features
Verify Database Schema: Always check /database/SCHEMA-VERIFICATION.md first
Update Documentation: Alongside code changes, not after
Jekyll Compatibility: Escape with tags
Mermaid Diagrams: Use <div class="mermaid"> not markdown code fences
Cross-References: Link related documentation sections
Timestamps: Add proper timestamps following CLAUDE.md format

🎯 Priority Documentation Areas

HIGHEST: /architecture/system-overview.md - System architecture understanding
HIGH: /core-systems/s-plings-io/ - Gateway service (universal scan entry point: QR / NFC / RFID)
HIGH: /use-cases/ - Requirements and business logic
MEDIUM: /api/ - Integration specifications
MEDIUM: /database/SCHEMA-VERIFICATION.md - Current database state

🔍 Finding Information Quickly

Common Agent Questions & Answers

Question	Location	File
How do scans (QR / NFC / RFID) work?	`/core-systems/s-plings-io/`	`README.md` + `routing-logic.md`
What’s the system architecture?	`/architecture/`	`system-overview.md`
How do I integrate the API?	`/api/`	`README.md` + `integration-examples.md`
What’s the database schema?	`/database/`	`SCHEMA-VERIFICATION.md` (READ THIS FIRST!)
How do object relationships work?	`/core-systems/`	`spatial-relationships.md`
What are the use cases?	`/use-cases/`	`overview.md`
How does authentication work?	`/api/`	`authentication.md`
What’s the frontend architecture?	`/frontend/`	`README.md`

🚨 Critical Files for Agents

/database/SCHEMA-VERIFICATION.md - Always read before database queries
/architecture/system-overview.md - Understand the multi-service ecosystem
/core-systems/s-plings-io/README.md - Universal scan entry point (QR / NFC / RFID)
/use-cases/overview.md - Business requirements and user stories
CLAUDE.md - Development guidelines and agent usage instructions

📝 Documentation Standards

Required Elements

Timestamps: Follow CLAUDE.md format with created/updated dates
Jekyll Front Matter: Include layout, title, nav_order for navigation
Target Audience: Specify who the documentation serves
Cross-References: Link to related documents
Examples: Include code examples and use cases

Jekyll Compatibility

Liquid Syntax: Escape {{ }} with {% raw %}{{ }}
Mermaid Diagrams: Use <div class="mermaid"> wrapper
Navigation: Files in _config.yml header_pages appear in site menu

🔄 Maintenance Notes

Single Source of Truth: This README.md is the canonical structure reference
Update Workflow: When structure changes, update this file first
Agent Training: CLAUDE.md points agents here for detailed structure
Live Site: Changes deploy automatically via GitHub Actions to docs.plings.io

This documentation structure reflects the Plings Universal Object Graph System’s sophisticated multi-service architecture with the s.plings.io Gateway layer as the intelligent routing hub for all physical object interactions.

Search Results: