configucci/docs/main.md

Project Guide: XML Environment Configuration Editor

1. Project Overview

This is a React-based web application designed to manage environment configurations stored in XML format. It allows users to:

• Load .xml configuration files (via file picker)
• View and edit environment variables
• Save changes with simulated persistence delay
• Generate valid XML output from in-memory data

The core idea is to provide a visual editor for XML-based engine configurations, particularly useful for applications that rely on structured environment definitions.

File format

Key Technologies

• TypeScript: Full type safety across the codebase
• React: Component-based UI architecture
• Vite: Fast development server and build system
• XML Parsing & Serialization: Custom logic in ConfigReader.tsx and EnvBuilder.ts

High-Level Architecture

User Interface (React)
    │
    ▼
File Chooser → ConfigReader → Config (JSON-like) → AppState
    │                         │             │
    └─────────→ EnvBuilder ←─┘             │
                            (Save/Update)│
                                      ▼
                                State Update (async)

---

2. Getting Started

Prerequisites

• Node.js (v16 or higher)
• npm or pnpm
• A modern browser (Chrome/Firefox)

Installation

# Clone the repo (if not already done)
git clone <your-repo-url>
cd your-project

# Install dependencies
npm install

# Start development server
npm run dev

Running Tests

No test files (*.test.ts) are present in the current codebase. Consider adding Jest or Vitest for future testing.

Basic Usage

1. Open the app in your browser.
2. Click "Create new" to initialize a default config with an DEFAULT environment.
3. Upload an .xml file using the file picker.
4. Edit environments and parameters in the UI.
5. Changes are saved asynchronously (simulated 1-second delay).

---

3. Project Structure

Directory	Purpose
src/	Main source code
src/App.tsx	Central state manager (AppState) and config loading/saving logic
src/main.tsx	React root rendering entry point
src/models/	Core data models and parsers (Env, EnvParam, ConfigReader)
src/builders/	Utilities to convert objects into XML strings (EnvBuilder)
src/components/	UI components (FileChoiser, Content)
src/vite-env.d.ts	Vite environment type definitions

Key Files

• App.tsx: Manages global state (AppState.Instance) and handles config loading/saving.
• ConfigReader.tsx: Parses XML into Config object. Uses DOM API to traverse nodes.
• EnvBuilder.ts: Serializes Env objects into valid XML strings using template literals.
• FileChoiser.tsx: Handles file input and creation of new configs.

---

4. Development Workflow

Coding Standards

• Use TypeScript with strict type checking (enforced by tsconfig.json)
• Follow React functional component patterns
• Use async/await for I/O operations (e.g., file parsing, saving)
• Avoid side effects in pure functions

Testing

Currently no tests are included. Add:

npm install --save-dev jest @testing-library/react @testing-library/jest-dom

Then create test files in __tests__/.

Build & Deployment

• Build: npm run build
• Output: dist/ directory
• Deploy static files via GitHub Pages, Vercel, Netlify, etc.

Contribution Guidelines

• Fork the repo and create a feature branch
• Write descriptive commit messages
• Open a PR with clear summary of changes
• Ensure no breaking changes without version bump

---

5. Key Concepts

Concept	Description
Env	Represents an environment (e.g., "DEV", "PROD") with a name and list of parameters
EnvParam	A key-value pair representing a configuration variable
Config	Root container for multiple Env objects
ConfigReader	Parses XML files into Config objects using DOM traversal
EnvBuilder	Converts Env objects back into valid XML strings
AppState	Singleton managing global state (currently only holds envs)

Design Patterns

• Singleton: AppState.Instance
• Builder Pattern: EnvBuilder for generating structured XML output
• Observer/State Management: saveEnv() updates state and logs, simulates async persistence

---

6. Common Tasks

Load a Config File

1. Click the file input button in the top-right.
2. Select an .xml file that follows the expected structure:

   <engine>
     <environment name="DEV">
       <parameter name="API_URL" value="http://localhost:3000" />
     </environment>
   </engine>
   

3. The app parses and loads it into memory.

Create a New Config

1. Click "Create new" in the FileChoiser.
2. A default config with one environment (DEFAULT) is created.
3. You can now edit or save it.

Save an Environment

• Call AppState.Instance.saveEnv(env) when updating.
• Returns a promise that resolves after 1 second (simulates backend delay).
• Index of the updated env is returned (-1 if not found).

Export to XML

• Use new EnvBuilder().src(env).build() to generate XML string from an Env.
• Useful for saving or sharing configurations.

---

7. Troubleshooting

Issue	Solution
File not loading	Ensure the file is .xml and valid (check structure in ConfigReader)
Missing envs after load	Verify ConfigReader.parse() returns a non-null Config
"Invalid Chalk template style argument" error	This comes from Content.tsx — likely a typo or placeholder. Should be replaced with proper error message.
XML not rendering correctly	Check that EnvBuilder uses correct escaping (\r\n, proper tags)

💡 Tip: Use browser DevTools to inspect the DOM and console logs during file parsing.

---

8. References

• Vite Documentation
• React Docs
• TypeScript Handbook
• XML DOM API (MDN)

🔗 Note: The XML schema used is not documented. You may want to define a .xsd or schema file for validation.