# Project Structure

This document describes the organized structure of the APAW project.

## Root Directory

```
APAW/
├── .kilo/                    # Kilo Code configuration
│   ├── agents/               # Agent definitions
│   ├── commands/             # Slash commands
│   ├── rules/                # Global rules
│   ├── skills/               # Agent skills
│   └── KILO_SPEC.md          # Kilo specification
├── docker/                   # Docker configurations
│   ├── Dockerfile.playwright # Playwright MCP container
│   ├── docker-compose.yml    # Base Docker config
│   └── docker-compose.web-testing.yml
├── scripts/                  # Utility scripts
│   └── web-test.sh           # Web testing script
├── tests/                    # Test suite
│   ├── scripts/              # Test scripts
│   │   ├── compare-screenshots.js
│   │   ├── console-error-monitor.js
│   │   └── link-checker.js
│   ├── visual/               # Visual regression
│   │   ├── baseline/         # Reference screenshots
│   │   ├── current/          # Current screenshots
│   │   └── diff/             # Diff images
│   ├── reports/              # Test reports
│   ├── console/              # Console logs
│   ├── links/                 # Link check results
│   ├── forms/                 # Form test data
│   ├── run-all-tests.js      # Main test runner
│   ├── package.json          # Test dependencies
│   └── README.md              # Test documentation
├── src/                      # Source code
├── archive/                  # Deprecated files
├── AGENTS.md                 # Agent reference
└── README.md                 # Project overview
```

## Docker Configurations

All Docker files are in `docker/`:

| File | Purpose |
|------|---------|
| `docker-compose.yml` | Base configuration |
| `docker-compose.web-testing.yml` | Web testing with Playwright MCP |
| `Dockerfile.playwright` | Custom Playwright container |

### Usage

```bash
# Start from project root
docker compose -f docker/docker-compose.web-testing.yml up -d

# Or create alias
alias dc='docker compose -f docker/docker-compose.web-testing.yml'
dc up -d
```

## Scripts

All utility scripts are in `scripts/`:

| Script | Purpose |
|--------|---------|
| `web-test.sh` | Run web tests with Docker |

### Usage

```bash
# Run from project root
./scripts/web-test.sh https://your-app.com

# With options
./scripts/web-test.sh https://your-app.com --auto-fix
./scripts/web-test.sh https://your-app.com --visual-only
```

## Tests

All tests are in `tests/`:

### Test Types

| Directory | Test Type |
|-----------|-----------|
| `visual/` | Visual regression testing |
| `console/` | Console error capture |
| `links/` | Link checking results |
| `forms/` | Form testing data |
| `reports/` | HTML/JSON reports |

### Running Tests

```bash
# From project root
cd tests && npm install && npm test

# Or use script
./scripts/web-test.sh https://your-app.com
```

## Archive

Deprecated files are in `archive/`:

- Old scripts
- Old documentation
- Old test files

Do not reference these files - they may be removed in future.

## Kilo Code Structure

`.kilo/` directory contains all Kilo Code configuration:

### Agents (`.kilo/agents/`)

Each agent has its own file with YAML frontmatter:

```yaml
---
model: ollama-cloud/qwen3-coder:480b
mode: subagent
color: "#DC2626"
description: Agent description
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  task:
    "*": deny
    "specific-agent": allow
---
```

### Commands (`.kilo/commands/`)

Slash commands available in Kilo Code:

| Command | Purpose |
|---------|---------|
| `/web-test` | Run web tests |
| `/web-test-fix` | Run tests with auto-fix |
| `/pipeline` | Run agent pipeline |

### Skills (`.kilo/skills/`)

Agent skills (capabilities):

| Skill | Purpose |
|-------|---------|
| `web-testing` | Web testing infrastructure |
| `playwright` | Playwright MCP integration |

### Rules (`.kilo/rules/`)

Global rules loaded for all agents:

- `global.md` - Base rules
- `lead-developer.md` - Developer rules
- `code-skeptic.md` - Code review rules
- etc.

## Environment Variables

### Web Testing

| Variable | Default | Description |
|----------|---------|-------------|
| `TARGET_URL` | `http://localhost:3000` | URL to test |
| `PLAYWRIGHT_MCP_URL` | `http://localhost:8931/mcp` | MCP endpoint |
| `PIXELMATCH_THRESHOLD` | `0.05` | Visual diff tolerance |
| `AUTO_CREATE_ISSUES` | `false` | Auto-create Gitea issues |
| `GITEA_TOKEN` | - | Gitea API token |
| `REPORTS_DIR` | `./tests/reports` | Output directory |

## Quick Reference

```bash
# Start Docker containers
docker compose -f docker/docker-compose.web-testing.yml up -d

# Run web tests
./scripts/web-test.sh https://your-app.com

# View reports
open tests/reports/web-test-report.html

# Stop containers
docker compose -f docker/docker-compose.web-testing.yml down
```