📚 Documentation Portal - Main Index

Welcome to the documentation for your DSL-based application

The portal has two kinds of content:

  • Framework Guides (GENERIC) — how every DSL application works: the interface, forms, navigation, deletion, deployment. Always shown.
  • Application Guides — the domain content for the application you are running (its tables, rules and workflows). Shown in the sidebar below the Framework Guides when the application provides them.

🎯 Quick Start by User Type

👤 I'm a New User (First Time Using This)

Time needed: 15-20 minutes

Start here to learn the basics: 1. Welcome & Overview - What is this application? 2. Tour the Interface - Learn the screen layout 3. Add Your First Record - Step-by-step tutorial 4. Navigate Records - Understanding relationships

Then: open your application's section in the sidebar for its overview and common workflows.

💻 I'm Setting Up Development (Running Locally)

Time needed: 20-30 minutes

  1. Local Development Setup - Run on your computer
  2. Environment Variables - Configure settings
  3. Your application's Setup guide (sidebar), if it has one

Then start development: - Run python server/run.py <app_name> and open the port listed in applications.yaml

🚀 I'm Deploying to Production

Time needed: 30-45 minutes

  1. Deployment Patterns - Generic deployment guide
  2. Environment Variables - Production config
  3. Your application's Operations guide (sidebar), if it has one

📖 I'm a New Developer

Time needed: 40-50 minutes

Start with framework concepts: 1. What Is DSL? - How apps are built 2. CRUD Operations - Data operations 3. Forms & Validation - Form system 4. Hierarchical Navigation - Parent-child relationships 5. Soft Delete Pattern - How deletion works

Then: your application's Quick Reference (sidebar) for its tables and fields.

🎓 I'm Already Experienced (Extending/Contributing)

Skip to: - Developer Reference - Framework internals and architecture - CLAUDE.md (repository root, not served here) - Project guidelines and patterns - Quick Reference Guide - Fast lookups

📚 Framework Documentation (GENERIC)

Framework-agnostic guides that apply to any DSL-based CRUD application

Getting Started (4 files)

Start here if new to the system: - 00_WELCOME.md - What is this application? - 01_THE_INTERFACE.md - Tour of the screen - 02_YOUR_FIRST_RECORD.md - Step-by-step tutorial - 03_NAVIGATION.md - Parent-child relationships

Core Concepts (5 files)

Understand how the framework works: - DSL_SYSTEM.md - Dynamic Scripting Language explained - CRUD_OPERATIONS.md - Create, Read, Update, Delete - FORMS_AND_VALIDATION.md - Form fields and validation - HIERARCHICAL_NAVIGATION.md - Nested records - SOFT_DELETE_PATTERN.md - Safe deletion system

Operations (3 files)

Run and deploy the application: - LOCAL_DEVELOPMENT.md - Development setup - DEPLOYMENT_PATTERNS.md - Production deployment - ENVIRONMENT_VARIABLES.md - Configuration reference

📁 Location: docs_portal/GENERIC/

📦 Application Documentation

Each application can ship its own portal section in apps/<app_name>/docs_portal/ (e.g. apps/container_tracking/docs_portal/, apps/road_maintenance/docs_portal/). The portal automatically shows the section belonging to the application you are running — typically:

  • Overview — the application's purpose and domain
  • Quick Reference — tables, fields and codes
  • Workflows — step-by-step task guides

Open it from the sidebar, below the Framework Guides.

🎯 Common Questions

I don't know where to start

→ Go to Quick Start by User Type above. Find your role and follow the steps.

I'm stuck on a problem

→ Check the FAQ for common issues and solutions.

I want to understand the whole system

→ Read GENERIC Getting Started (4 files), then GENERIC Core Concepts (5 files). Then read your application's Overview.

I just want to run the app locally

→ Follow Local Development.

I need to deploy to production

→ Read Deployment Patterns, then your application's Operations guide if it has one.

Where do I find information about a specific table?

→ Your application's Quick Reference, in the sidebar.

How do I perform a specific task?

→ Your application's Workflows guide, in the sidebar.

  • Developer Reference - Framework architecture and internals
  • Project Guidelines - CLAUDE.md in the repository root (not served here)
  • Quick Reference - Fast command and path lookup

💡 Documentation Principles

  1. Separation of Concerns
  2. GENERIC files: framework concepts, reusable across any DSL app

  3. Application files: domain-specific content, shown only for the running app

  4. Progressive Learning

  5. Getting Started: 15-20 minutes to functional user
  6. Core Concepts: 30-40 minutes to understand framework

  7. Operations: 20-30 minutes to deploy

  8. Practical Examples

  9. Every guide has step-by-step instructions and troubleshooting

  10. Cross-Referencing

  11. Links between related topics, no duplication

Questions? Check the FAQ or start with your user type above.