================================================================================
                     CARBONCORE DEVELOPER GUIDE #04
              UNIVERSAL TERRITORY DETAILS SERVICE
================================================================================

PRINCIPLE: Single entry point for territory information from ALL modules

================================================================================
SERVICE ARCHITECTURE
================================================================================

File: js/service/details-data-service.js
Global Object: window.TerritoryDetailsService

Purpose:
    - Unified modal window for territory details
    - Accessible from ALL platform modules
    - Consistent data display
    - Single source of truth

Core Methods:
    showDetails(territoryId)    - Main entry point
    findTerritory(territoryId)  - Locate territory data
    createModal(territory)      - Generate modal window
    setupEventListeners()       - Attach handlers
    initializeModalContent()    - Load async data

================================================================================
USAGE FROM DIFFERENT MODULES
================================================================================

Module 1: Territory List
Location: territory-list.js
Event: "Details" button click

Code:
    const detailsButton = document.querySelector('.details-btn');
    detailsButton.addEventListener('click', function() {
        const territoryId = this.getAttribute('data-territory-id');
        window.TerritoryDetailsService.showDetails(territoryId);
    });

Module 2: Token Management
Location: token-management.js
Event: "Territory Details" button

Code:
    showTerritoryDetails(territoryId) {
        window.TerritoryDetailsService.showDetails(territoryId);
    }

Module 3: Territory Map
Location: territory-map.js
Event: Map marker popup

Code:
    function showTerritoryDetails(territoryId) {
        window.TerritoryDetailsService.showDetails(territoryId);
    }

    // Popup HTML
    <button onclick="showTerritoryDetails('${territoryId}')">
        View Details
    </button>

Module 4: OTC Marketplace
Location: deals-manager.js
Event: Deal with territory link

Code:
    const territoryId = this.extractTerritoryIdFromDeal(deal);
    if (territoryId) {
        window.TerritoryDetailsService.showDetails(territoryId);
    }

Module 5: Requests Manager
Location: requests-manager.js
Event: Territory info button

Code:
    function showTerritoryInfo(territoryId) {
        window.TerritoryDetailsService.showDetails(territoryId);
    }

================================================================================
DATA SOURCE PRIORITY
================================================================================

Search Order:
    1. window.territoryState.filteredTerritories (active filters)
    2. window.territoryState.territories (all loaded)
    3. Token data (if coming from token management)
    4. Request data (if coming from requests)

Function: findTerritory(territoryId)

Code:
    findTerritory: function(territoryId) {
        const id = territoryId.toString();

        // Check filtered territories
        if (window.territoryState?.filteredTerritories) {
            const territory = window.territoryState
                .filteredTerritories
                .find(t => t.id.toString() === id);
            if (territory) return territory;
        }

        // Check all territories
        if (window.territoryState?.territories) {
            const territory = window.territoryState
                .territories
                .find(t => t.id.toString() === id);
            if (territory) return territory;
        }

        return null;
    }

================================================================================
MODAL STRUCTURE
================================================================================

Container: #territory-details-modal-container
Class: modal-container

Layout:
    <div class="modal-content territory-details-modal">
        <div class="modal-header">
            <h2>Territory Details: {name}</h2>
            <button class="close-modal">&times;</button>
        </div>

        <div class="modal-body">
            <!-- Tab Navigation -->
            <div class="territory-details-tabs">
                <button class="tab-button active" data-tab="general">
                    General Info
                </button>
                <button class="tab-button" data-tab="tokens">
                    Tokens
                </button>
                <button class="tab-button" data-tab="verification">
                    Verification
                </button>
                <button class="tab-button" data-tab="validation">
                    Standards & Insurance
                </button>
            </div>

            <!-- Tab Contents -->
            <div class="tab-content active" id="general-tab">
                {generalTabHTML}
            </div>

            <div class="tab-content" id="tokens-tab">
                <div id="territory-tokens-container">
                    Loading...
                </div>
            </div>

            <div class="tab-content" id="verification-tab">
                <div id="territory-verification-container">
                    {verificationTabHTML}
                </div>
            </div>

            <div class="tab-content" id="validation-tab">
                <div id="territory-validation-container">
                    {validationTabHTML}
                </div>
            </div>
        </div>
    </div>

================================================================================
TAB 1: GENERAL INFORMATION
================================================================================

Function: generateGeneralTabHTML(territory)

Content:
    1. Territory Map
        - Full-size Leaflet map
        - Boundary polygon
        - Pan/zoom enabled

    2. Basic Information
        - Territory ID
        - Name
        - Type
        - Area (hectares)
        - Country/Region
        - Coordinates

    3. Status Information
        - Current status badge
        - Status description
        - Created/Updated dates
        - Verification expiry

    4. Owner Information
        - Owner wallet address
        - Owner UID
        - Registration date

    5. CO2 Data (if verified)
        - Annual CO2 absorption
        - Oxygen production
        - Daily token rate

Map Initialization:
    setTimeout(() => {
        const mapContainer = document.getElementById('territory-map-details');
        const map = L.map(mapContainer).setView([0, 0], 2);

        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png')
            .addTo(map);

        if (territory.boundaryGeoJson) {
            const geoJson = JSON.parse(territory.boundaryGeoJson);
            const layer = L.geoJSON(geoJson).addTo(map);
            map.fitBounds(layer.getBounds());
        }
    }, 100);

================================================================================
TAB 2: TOKEN INFORMATION
================================================================================

Function: loadTokenData(territory)

Process:
    1. Check existing tokens in territory object
    2. If no tokens: Query CarbonCreditFactory
    3. For each project:
        - Get token contract address
        - Load token metadata
        - Check user balance
        - Get total supply
    4. Display token cards

Token Display:
    FOR each token:
        <div class="token-info-card">
            <div class="token-header">
                {symbol} - Vintage {year}
            </div>
            <div class="token-details">
                Contract: {address}
                Total Supply: {supply}
                Your Balance: {balance}
                Daily Rate: {rate} tokens/day
            </div>
            <div class="token-actions">
                <button>View in MetaMask</button>
                <button>Copy Address</button>
                <button>View on Explorer</button>
            </div>
        </div>

No Tokens:
    <div class="no-tokens-message">
        <p>No token contracts found for this territory.</p>
        <p>Status must be "Issuance-Ready" to create project.</p>
    </div>

================================================================================
TAB 3: VERIFICATION HISTORY
================================================================================

Function: generateVerificationTabHTML(territory)

Expert Verification Section:
    Expert: {expertAddress}
    Report URI: {reportUri}
    Oxygen Production: {oxygenProduction} kg/year
    CO2 Absorption: {co2Absorption} kg/year
    Approved: {approved}
    Notes: {notes}
    Timestamp: {timestamp}

Government Verification Section:
    Government Entity: {governmentAddress}
    Report URI: {reportUri}
    Approved: {approved}
    Validity Period: {validityPeriod} seconds
    Expiration: {expirationDate}
    Notes: {notes}
    Timestamp: {timestamp}

Verification Timeline:
    1. Territory Created - {createdAt}
    2. Expert Claimed - {claimedAt}
    3. Expert Verified - {expertVerifiedAt}
    4. Government Verified - {governmentVerifiedAt}
    5. Project Created - {projectCreatedAt}

================================================================================
TAB 4: STANDARDS & INSURANCE
================================================================================

Function: generateValidationTabHTML(territory)

Content (Future Implementation):
    1. Certification Standards
        - Paris Agreement Article 6
        - VCS (Verified Carbon Standard)
        - Gold Standard
        - GFW Methodology

    2. Insurance Coverage
        - Coverage amount
        - Policy number
        - Expiration date
        - Provider

    3. Compliance Documents
        - Validation reports
        - Verification reports
        - Certificates
        - Audit trails

Current Status:
    <p>Standards validation and insurance information
       will be displayed here.</p>

================================================================================
EVENT HANDLING
================================================================================

Function: setupModalEventListeners(modalContainer, territory)

Close Button:
    const closeButton = modalContainer.querySelector('.close-modal');
    closeButton.addEventListener('click', () => {
        modalContainer.remove();
    });

Background Click:
    modalContainer.addEventListener('click', (e) => {
        if (e.target === modalContainer) {
            modalContainer.remove();
        }
    });

Escape Key:
    document.addEventListener('keydown', (e) => {
        if (e.key === 'Escape') {
            modalContainer.remove();
        }
    });

Tab Switching:
    const tabButtons = modalContainer.querySelectorAll('.tab-button');
    tabButtons.forEach(button => {
        button.addEventListener('click', () => {
            // Remove active from all
            tabButtons.forEach(b => b.classList.remove('active'));
            modalContainer.querySelectorAll('.tab-content')
                .forEach(c => c.classList.remove('active'));

            // Add active to clicked
            button.classList.add('active');
            const tabId = button.getAttribute('data-tab');
            modalContainer.querySelector(`#${tabId}-tab`)
                .classList.add('active');
        });
    });

================================================================================
ASYNC DATA LOADING
================================================================================

Function: initializeModalContent(modalContainer, territory)

Sequence:
    1. Initialize Map (100ms delay)
        - Wait for DOM render
        - Create Leaflet instance
        - Add territory boundary

    2. Load Token Data (async)
        - Check existing tokens
        - Query contracts if needed
        - Display results

    3. Load Verification Data (async)
        - Expert verification
        - Government verification
        - Validation status

    4. Load Standards Data (future)
        - Certification standards
        - Insurance coverage

Loading States:
    Initial: <div class="loading-spinner">Loading...</div>
    Error: <div class="error-message">{error}</div>
    No Data: <div class="no-data-message">No data available</div>
    Success: Display actual content

================================================================================
CSS STYLING
================================================================================

Modal Container:
    position: fixed
    top: 0
    left: 0
    width: 100%
    height: 100%
    background: rgba(0, 0, 0, 0.5)
    z-index: 10000
    overflow-y: auto

Modal Content:
    max-width: 900px
    margin: 50px auto
    background: white
    border-radius: 12px
    box-shadow: 0 20px 60px rgba(0,0,0,0.3)

Tabs:
    display: flex
    border-bottom: 2px solid #e0e0e0
    margin-bottom: 20px

Tab Button:
    padding: 12px 24px
    background: none
    border: none
    cursor: pointer
    transition: all 0.2s

Tab Button Active:
    border-bottom: 3px solid var(--primary-green)
    color: var(--primary-green)

================================================================================
GLOBAL STATE INTEGRATION
================================================================================

Territory State Object:
    window.territoryState = {
        territories: [],         // All loaded territories
        filteredTerritories: [], // Currently filtered
        selectedTerritory: null, // Currently viewing
        mapInstance: null        // Map reference
    };

Update After Changes:
    // After territory update
    const updatedTerritory = await loadTerritoryData(territoryId);
    const index = window.territoryState.territories
        .findIndex(t => t.id === territoryId);
    window.territoryState.territories[index] = updatedTerritory;

    // Refresh details if open
    if (isDetailsModalOpen(territoryId)) {
        window.TerritoryDetailsService.showDetails(territoryId);
    }

================================================================================