Prototype-autonom-ia-OS

Documentation for the Phoenix Workspace & Engine Architecture

This repository provides comprehensive documentation on the technical architecture, software topology, and operation of the application named Prototype autonom ia OS.

Overview of the Architecture

The application is designed with a modular full-stack architecture consisting of:

• Client (Front-end): Utilizes React 18, TypeScript, Tailwind CSS, and Vite.
• Server (Back-end): Built on Express (Node.js) operating on port 3000.
• Inference Engine: Integrates the official SDK @google/genai on the server, with a local deterministic fallback mode (costing $0 in tokens).

Project Folder Structure

The project follows a well-organized folder structure that includes:

/
├── server.ts                       # Main Express server & API relay
├── src/
│   ├── App.tsx                     # Root component and desktop manager
│   ├── components/                 # User interface components (Desktop, Dock, Windows)
│   │   ├── dock/                   # Taskbar, controls, and panels
│   │   ├── modals/                 # Modals and settings windows
│   │   └── ui/                     # Reusable UI elements
│   ├── services/                   # Business logic & integrations
│   │   ├── agents/                 # API routing services
│   │   ├── export/                 # Standalone bundle generator
│   │   ├── agentMeshHub.ts         # Inter-module communication hub
│   │   └── aiStudioService.ts      # AI integration service
│   ├── types.ts                    # Type definitions for TypeScript
│   └── main.tsx                    # React entry point
├── prompts/                        # Rule files and system instructions
└── metadata.json                   # Application metadata

Module Functionality & Data Flow

1. User Interface (Virtual Desktop):

   • Users interact with working windows (Terminal, Editor, Settings) integrated into a dynamic desktop environment.

2. Secure Server Relay (/server.ts):

   • API requests to language models are processed exclusively through the local server (/api/chat or /api/generate). The API keys are stored server-side via process.env.GEMINI_API_KEY and are never exposed to the client browser.

3. Self-Healing Pipeline:

   • When scripts or code checks are executed, the server captures error logs. In the event of an error, the system attempts a syntax correction in a closed loop (limited to 3 attempts for safety reasons).

4. Local Fallback Mode:

   • If no API key is provided in the environment, the system automatically switches to a deterministic local execution engine without interrupting the user interface.

Security & Best Practices

• Secret Management: Secrets are declared in .env.example and loaded as environment variables.
• Port Isolation: The server listens on 0.0.0.0:3000 in accordance with network configuration.
• Client-Side Security: No sensitive keys are stored in plain text in the source code.

This documentation serves to facilitate maintenance and understanding of the project architecture.