# Project Structure

## Root Directory Organization

```
rpa_vision_v3/
├── core/                   # Core system modules (5-layer architecture)
├── agent_v0/              # Cross-platform capture agent
├── server/                # API server and processing pipeline
├── web_dashboard/         # Flask web dashboard (port 5001)
├── visual_workflow_builder/ # React/TypeScript workflow editor
├── command_interface/     # Simple web command interface
├── gui/                   # PyQt5 desktop application
├── data/                  # Runtime data storage
├── tests/                 # Comprehensive test suite
├── examples/              # Usage examples and demos
├── docs/                  # Documentation and specifications
└── training_data/         # ML training datasets
```

## Core Architecture (`core/`)

Organized by the 5-layer architecture:

```
core/
├── models/          # Data structures for all layers (0-4)
├── capture/         # Layer 0: Raw event capture
├── detection/       # Layer 2: UI element detection
├── embedding/       # Layer 3: Multi-modal embeddings & FAISS
├── graph/           # Layer 4: Workflow graph construction
├── execution/       # Action execution and robustness
├── matching/        # Similarity matching algorithms
├── learning/        # Continuous learning and feedback
├── healing/         # Self-healing strategies
├── workflow/        # Workflow composition and management
├── analytics/       # Performance monitoring and insights
├── monitoring/      # Admin monitoring and automation
├── persistence/     # Data storage and retrieval
├── pipeline/        # Processing pipelines
├── training/        # ML model training
├── variants/        # UI variant handling
└── gpu/            # GPU resource management
```

## Data Organization (`data/`)

```
data/
├── sessions/        # RawSession JSON files
├── screen_states/   # ScreenState processed data
├── embeddings/      # Vector embeddings (.npy files)
├── faiss_index/     # FAISS similarity indices
├── workflows/       # Workflow graph definitions
├── screenshots/     # Captured screenshots
├── training/        # Training data and uploads
├── analytics/       # Analytics data storage
├── healing/         # Self-healing learning data
└── diagnostics/     # System diagnostic data
```

## Testing Structure (`tests/`)

```
tests/
├── unit/           # Unit tests for individual components
├── integration/    # Integration tests across components
├── property/       # Property-based tests (Hypothesis)
├── performance/    # Performance benchmarks
└── fixtures/       # Test data and fixtures
```

## Component Applications

- **`agent_v0/`**: Standalone capture agent with encryption and cross-platform support
- **`server/`**: Production API server with processing pipeline and queue management
- **`web_dashboard/`**: Flask-based monitoring dashboard
- **`visual_workflow_builder/`**: Full-stack React/TypeScript workflow editor
- **`gui/`**: PyQt5 desktop application for local use

## Naming Conventions

### Files
- **Python modules**: `snake_case.py`
- **Classes**: `PascalCase`
- **Functions/variables**: `snake_case`
- **Constants**: `UPPER_SNAKE_CASE`

### Directories
- **Core modules**: `snake_case`
- **Data directories**: `snake_case`
- **Component apps**: `snake_case`

### Data Files
- **Sessions**: `rawsession_YYYY-MM-DDTHH-MM-SS_userID.json`
- **Screenshots**: `shot_NNNN.png` (within session directories)
- **Embeddings**: `embedding_sessionID_stateID.npy`
- **Workflows**: `workflow_name_version.json`

## Configuration Management

- **Central config**: `core/config.py` with dataclass-based configuration
- **Environment files**: `.env` (local), `.env.example` (template)
- **Component configs**: Each component has its own config handling
- **Production overrides**: Environment variables take precedence

## Import Patterns

```python
# Core imports
from core.models import RawSession, ScreenState, UIElement
from core.detection import create_detector
from core.embedding import FusionEngine
from core.graph import GraphBuilder, NodeMatcher

# Component imports
from agent_v0.storage_encrypted import EncryptedStorage
from server.processing_pipeline import ProcessingPipeline
from web_dashboard.app import create_app
```