Plings Documentation
Created: Tue 29 Jul 2025 07:14:58 CEST
Updated: Tue 29 Jul 2025 07:34:45 CEST - Updated file references after renaming and creation tasks
Document Version: 1.1 - Updated structure with latest file changes
Security Classification: Internal Technical Documentation
Target Audience: Developers, AI Agents, Technical Writers
Author: Paul Wisén
Quick Navigation for AI Agents
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
Directory Structure Overview
🏗️ Core Architecture
/architecture/
├── README.md # Architecture overview and principles
├── system-overview.md # HIGH-PRIORITY: Multi-service ecosystem, Director 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/ # ⭐ NEW: Director service documentation
│ ├── README.md # Director 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 Director | /core-systems/s-plings-io/ |
Reference in architecture | Critical routing service |
| 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.mdfirst - Update Documentation: Alongside code changes, not after
- Jekyll Compatibility: Escape
withtags - 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/- Director service (universal QR entry point) - 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 does QR scanning 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 QR entry point/use-cases/overview.md- Business requirements and user storiesCLAUDE.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.ymlheader_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 Director layer as the intelligent routing hub for all physical object interactions.