# 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](file_format_spec.md)

### 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
```bash
# 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:
```bash
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:
   ```xml
   <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](https://vitejs.dev/guide/)
- [React Docs](https://react.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
- [XML DOM API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/XML_DOM)

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