---
name: appbase-module-example
version: 1.0.0
description: Foundation module that provides essential system capabilities including code management (appcodes/appcodes_kv tables) and parameter management, required by all web applications in the ecosystem.
trigger_conditions:
  - User needs to understand the base module functionality
  - Task involves code management or system parameters
  - Building applications that require foundational appbase capabilities
  - Reference implementation for base system modules
---

# AppBase Module Example

## Overview
The appbase module is a foundational component required by all web applications in the ecosystem. It provides two critical system capabilities:

1. **Code Management**: Hierarchical key-value pair management through `appcodes` and `appcodes_kv` tables
2. **Parameter Management**: Centralized system parameter storage with business date functionality

This module serves as the base layer for all applications, enabling consistent configuration and coding standards across the platform.

## Module Structure Analysis

### Core Directory Structure
```
appbase/                       # Main module directory
├── appbase/                   # Python package
│   ├── __init__.py           # Python package marker
│   ├── init.py               # Module initialization (load_appbase function)
│   ├── params.py             # Parameter management logic
│   ├── businessdate.py       # Business date functionality
│   └── version.py            # Version information
├── json/                      # CRUD definition files
│   ├── appcodes.json         # Code management CRUD
│   ├── appcodes_kv.json      # Code key-value CRUD (hierarchical)
│   ├── params.json           # System parameters CRUD
│   └── svgicon.json          # SVG icon management
├── models/                    # Database table definitions (.xlsx format)
│   ├── appcodes.xlsx         # Code table definition
│   ├── appcodes_kv.xlsx      # Code key-value table definition
│   ├── params.xlsx           # Parameters table definition
│   └── svgicon.xlsx          # SVG icons table definition
├── wwwroot/                   # Frontend scripts and resources
│   ├── appcodes/             # Code management UI scripts
│   ├── appcodes_kv/          # Code key-value UI scripts (hierarchical)
│   ├── params/               # Parameter management UI scripts
│   ├── svgicon/              # SVG icon management UI scripts
│   ├── get_code.dspy         # Code retrieval script
│   ├── get_appcodes_kv.dspy  # Code key-value retrieval script
│   ├── menu.ui               # Navigation menu template
│   └── show_icon.dspy        # Icon display script
├── pyproject.toml             # Modern Python packaging
├── requirements.txt           # Dependencies
└── README.md                  # Module documentation
```

## Key Implementation Patterns

### 1. Module Initialization (init.py)
The `load_appbase()` function exposes essential business date functions:

```python
def load_appbase():
    g = ServerEnv()
    g.get_business_date = get_business_date
    g.new_business_date = new_business_date
```

### 2. Hierarchical Code Management
The appbase module implements sophisticated hierarchical code management:

**appcodes.json** (Parent codes):
- Manages top-level code definitions
- Includes subtable relationship to appcodes_kv for key-value pairs
- Supports hierarchy flag to determine single vs multi-level codes

**appcodes_kv.json** (Hierarchical key-values):
- Implements true hierarchical structure with self-referencing parentid
- Conditional subtables based on hierarchy_flg parameter
- Dynamic parameter passing between parent and child records
- Sort order by key (k) and value (v) fields

### 3. Business Date Functionality
- Business date stored in params table
- `get_business_date()`: Retrieve current system business date
- `new_business_date()`: Set new business date
- Essential for financial and time-sensitive applications

### 4. System Parameter Management
- Centralized parameter storage in params table
- Dynamic parameter maintenance capability
- Accessible to all application modules

## Compliance Verification

### ✅ Module Development Specification Compliance
- [x] Proper directory structure with appbase/, wwwroot/, json/, models/
- [x] Correct init.py with load_appbase() function
- [x] ServerEnv exposure of business date functions
- [x] CRUD definitions in json/ directory
- [x] Frontend resources organized by feature in wwwroot/
- [x] Database table definitions in models/ directory

### ⚠️ Minor Notes
- Missing `init/data.json` (optional if no initialization data needed)
- Uses modern `pyproject.toml` instead of legacy `setup.py`

## Integration Requirements

### Essential for All Applications
The appbase module must be loaded before any application-specific modules because it provides:
- **Code lookup functionality**: Used by all modules for dropdown selections and validation
- **Parameter access**: System-wide configuration values
- **Business date context**: Critical for time-based operations
- **Icon management**: SVG icon storage and retrieval

### Code Management Usage Pattern
Applications use appbase codes through the documented encoding pattern:
- **appcodes table**: Stores code definitions with hierarchy_flg ('0'=single-level, '1'=multi-level)
- **appcodes_kv table**: Stores actual key-value pairs with hierarchical relationships
- Frontend components automatically integrate with code data for form controls

## Learning Points

### Hierarchical CRUD Implementation
The appcodes_kv.json demonstrates advanced CRUD patterns:
- Conditional subtables based on runtime parameters
- Parameter inheritance between parent and child CRUD instances
- Self-referencing hierarchical relationships
- Dynamic field exclusion based on context

### Foundation Module Design
- Minimal but essential functionality exposure
- Focus on system-wide utilities rather than business logic
- Robust parameter and code management infrastructure
- Clean separation between data storage and business functions

## Usage as Base Reference

This module serves as the foundation reference for:
1. **Base Module Structure**: How to organize essential system capabilities
2. **Hierarchical Data Patterns**: Implementing parent-child relationships in CRUD
3. **System Integration**: Providing services consumed by all other modules
4. **Parameter Management**: Centralized configuration storage and access
5. **Code Standardization**: Consistent encoding management across applications