# Project Structure

This document describes the organized structure of the APAW project.

## Root Directory

```
APAW/
├── .architect/               # Project codebase map (auto-indexed)
│   ├── README.md              # Navigation index
│   ├── project.json           # Machine-readable project metadata
│   ├── state.json             # Index freshness state (hashes, timestamps)
│   ├── architecture/          # Architecture overview and dependency graph
│   ├── entities/              # Domain entities, fields, relationships
│   ├── db-schema/             # Database tables, columns, indexes
│   ├── api-surface/          # API endpoints, methods, auth
│   ├── conventions/           # Naming, patterns, forbidden practices
│   ├── maps/                  # Programmatic file/module graphs (.gitignored)
│   └── tech-stack/            # Languages, frameworks, databases, tools
├── .kilo/                    # Kilo Code configuration
│   ├── agents/               # 30 agent definitions (YAML frontmatter)
│   │   ├── orchestrator.md   # Main dispatcher
│   │   ├── php-developer.md  # PHP/Laravel/Symfony/WordPress
│   │   ├── python-developer.md # Python/Django/FastAPI
│   │   ├── lead-developer.md # Primary code writer
│   │   ├── code-skeptic.md   # Adversarial review
│   │   └── ... (25 more)
│   ├── commands/             # Slash commands
│   │   ├── pipeline.md       # Full agent pipeline
│   │   ├── laravel.md        # Laravel web app pipeline
│   │   ├── nextjs.md         # Next.js app pipeline
│   │   ├── vue.md            # Vue/Nuxt app pipeline
│   │   ├── wordpress.md     # WordPress development pipeline
│   │   ├── feature.md        # Feature development
│   │   ├── commerce.md       # E-commerce site
│   │   └── ... (15 more)
│   ├── rules/                # Global rules (loaded for all agents)
│   │   ├── global.md         # Base rules
│   │   ├── atomic-tasks.md   # 1 action = 1 task principle
│   │   ├── modular-code.md  # Modules, libraries, microservices
│   │   ├── token-optimization.md  # Token budget rules
│   │   ├── gitea-centric-workflow.md  # Gitea as center of work
│   │   └── ... (10 more)
│   ├── skills/               # Agent skills
│   │   ├── php-laravel-patterns/   # Laravel patterns
│   │   ├── php-symfony-patterns/  # Symfony patterns
│   │   ├── php-wordpress-patterns/ # WordPress patterns
│   │   ├── php-security/          # OWASP, CSRF, XSS
│   │   ├── php-testing/           # PHPUnit, Pest
│   │   ├── php-modular-architecture/  # Module separation
│   │   ├── agent-logging/          # Execution logging
│   │   ├── gitea-workflow/         # Gitea integration (auto-detect project)
│   │   ├── gitea-commenting/       # Comment format (auto-detect project)
│   │   └── ... (30+ more)
│   ├── shared/               # Shared modules
│   │   ├── gitea-api.md      # Centralized API client (auto-detect repo)
│   │   ├── gitea-auth.md     # Centralized auth (env vars, no hardcoded creds)
│   │   ├── gitea-commenting.md # Comment format
│   │   └── self-evolution.md # Evolution protocol
│   ├── logs/                 # Execution logs
│   │   ├── agent-executions.jsonl  # Every agent invocation
│   │   ├── fitness-history.jsonl   # Fitness scores
│   │   └── efficiency_score.json   # Efficiency history
│   ├── capability-index.yaml # Agent capabilities & routing
│   ├── gitea.jsonc           # Gitea auth structure (env var mapping, NO secrets)
│   ├── kilo.jsonc           # Primary agent config
│   ├── KILO_SPEC.md          # Specification
│   └── EVOLUTION_LOG.md      # Evolution timeline
├── agent-evolution/          # Evolution Dashboard
│   ├── index.standalone.html # Standalone dashboard
│   ├── scripts/              # Sync & build scripts
│   ├── data/                 # Agent version history
│   └── docker-compose.yml    # Docker launch
├── scripts/                  # Utility scripts
│   └── agent-stats.ts        # Agent execution statistics
├── docker/                   # Docker configurations
│   ├── Dockerfile.playwright # Playwright MCP container
│   ├── Dockerfile.architect-indexer # Project indexer container
│   ├── docker-compose.yml    # Base config
│   ├── docker-compose.architect.yml # Architect indexer service
│   └── docker-compose.web-testing.yml
├── AGENTS.md                 # Agent reference (main config)
├── STRUCTURE.md              # This document
└── README.md                 # Project overview
```

## Key Configuration Files

### capability-index.yaml

Maps agent capabilities for orchestrator routing:

### `.architect/` Directory (Project Brain)

Auto-indexed codebase map that all agents read before starting work:

| File | Purpose |
|------|---------|
| `.architect/README.md` | Navigation index (auto-updated) |
| `.architect/project.json` | Machine-readable project metadata |
| `.architect/state.json` | Index freshness (hashes, timestamps) |
| `.architect/architecture/overview.md` | Architecture pattern, layers |
| `.architect/architecture/dependency-graph.md` | Module dependency graph |
| `.architect/entities/entities.md` | Domain entities, relations |
| `.architect/db-schema/schema.md` | Tables, columns, indexes, FKs |
| `.architect/api-surface/endpoints.md` | API routes, methods, auth |
| `.architect/conventions/conventions.md` | Coding standards, patterns |
| `.architect/tech-stack/stack.md` | Languages, frameworks, versions |
| `.architect/maps/file-graph.json` | File imports/exports graph |
| `.architect/maps/module-graph.json` | Module dependencies graph |

See `.kilo/skills/project-mapping/SKILL.md` for full documentation.

### capability-index.yaml

Maps agent capabilities for orchestrator routing:

```yaml
agents:
  php-developer:
    capabilities:
      - php_web_development
      - laravel_development
      - symfony_development
      - wordpress_development
    model: ollama-cloud/qwen3-coder:480b
    mode: subagent
    delegates_to:
      - code-skeptic
      - security-auditor

capability_routing:
  php_web_development: php-developer
  laravel_development: php-developer
```

### kilo.jsonc

Primary agents configuration:

```jsonc
{
  "model": "ollama-cloud/glm-5.1",
  "default_agent": "orchestrator",
  "agent": {
    "orchestrator": { "model": "ollama-cloud/glm-5.1", "variant": "thinking" },
    "code": { "model": "ollama-cloud/qwen3-coder:480b" },
    "ask": { "model": "ollama-cloud/glm-5.1", "variant": "instant" },
    "plan": { "model": "ollama-cloud/nemotron-3-super" },
    "debug": { "model": "ollama-cloud/glm-5.1", "variant": "thinking" }
  }
}
```

## Rules System

Rules in `.kilo/rules/` are loaded globally for all agents:

### Critical Rules

| Rule | Purpose |
|------|---------|
| `atomic-tasks.md` | 1 action = 1 task, max 100 lines/file, task sizing |
| `modular-code.md` | Modules, services, repositories, events |
| `token-optimimization.md` | Token budgets, no scope creep |
| `gitea-centric-workflow.md` | Issues before work, progress tracking, research |
| `global.md` | Base coding rules |

### Language-Specific Rules

| Rule | Purpose |
|------|---------|
| `php.md` | PSR-12, TDD, security |
| `nodejs.md` | Express, JWT, async |
| `go.md` | Error wrapping, context, table-driven tests |
| `flutter.md` | Riverpod, Clean Architecture |
| `docker.md` | Multi-stage, security |

## Skills System

Skills are capability modules agents reference:

### PHP Development

| Skill | Lines | Purpose |
|-------|-------|---------|
| `php-laravel-patterns` | 403 | Routing, Eloquent, Services, Repositories, Auth, Queues |
| `php-symfony-patterns` | 233 | Controllers, Doctrine, Messenger, Voters |
| `php-wordpress-patterns` | 276 | Plugins, CPT, REST API, Security |
| `php-security` | 147 | OWASP Top 10, CSRF, XSS, SQL injection |
| `php-testing` | 242 | PHPUnit, Pest, Dusk browser tests |
| `php-modular-architecture` | 242 | Module separation, interfaces, events |

### Frontend Frameworks

| Skill | Lines | Purpose |
|-------|-------|---------|
| `nextjs-patterns` | 290 | Next.js 14+ App Router, Server Components, Server Actions, Auth.js |
| `vue-nuxt-patterns` | 270 | Vue 3 / Nuxt 3 Composition API, Pinia, Nitro, SSR |
| `react-patterns` | 240 | React 18+ hooks, Context, TanStack Query, React Hook Form |

### Python Development

| Skill | Lines | Purpose |
|-------|-------|---------|
| `python-django-patterns` | 200 | Django models, DRF, services, repositories |
| `python-fastapi-patterns` | 230 | FastAPI async, Pydantic, SQLAlchemy, dependencies |

### Infrastructure

| Skill | Purpose |
|-------|---------|
| `gitea-workflow` | Issue creation, quality gates, progress tracking |
| `gitea-commenting` | Comment format with auto-project detection |
| `agent-logging` | Execution logging to agent-executions.jsonl |
| `docker-compose` | Docker Compose patterns |
| `docker-swarm` | Docker Swarm orchestration |

## Execution Logging

Every agent invocation is logged to `.kilo/logs/agent-executions.jsonl`:

```jsonl
{"ts":"2026-04-18T14:00:00Z","agent":"php-developer","issue":42,"project":"UniqueSoft/my-shop","task":"Create Product model","subtask_type":"model_creation","duration_ms":45000,"tokens_used":8500,"status":"success","files":["app/Models/Product.php"],"score":8,"next_agent":"code-skeptic"}
```

### Required Fields

| Field | Description |
|-------|-------------|
| `agent` | Agent name |
| `issue` | Gitea issue number |
| `project` | Target project repo (auto-detected, NOT hardcoded) |
| `task` | Atomic task description |
| `duration_ms` | Execution time |
| `tokens_used` | Token estimate |
| `status` | success/fail/pass/blocked |
| `score` | Self-assessment 1-10 |
| `next_agent` | Next agent in pipeline |

### Statistics

```bash
bun run agent:stats              # Last 30 days
bun run agent:stats:week         # Last 7 days
bun run agent:stats:project      # Filter by project
```

## Gitea Integration

### Centralized Authentication

All Gitea API calls use `get_gitea_token()` from `.kilo/shared/gitea-auth.md`. Configuration structure in `.kilo/gitea.jsonc` maps env var names — no actual credentials in code.

### Critical: Target Project Detection

Issues MUST be created in the target project, NOT in APAW:

```python
def get_target_repo():
    """Auto-detect from git remote - NEVER hardcode"""
    result = subprocess.run(['git', 'remote', 'get-url', 'origin'], capture_output=True, text=True)
    match = re.search(r'[:/]([^/]+/[^/]+?)(?:\.git)?$', result.stdout.strip())
    if match:
        return match.group(1)
    return os.environ.get('GITEA_TARGET_REPO', 'UniqueSoft/APAW')
```

All API calls use `get_target_repo()` instead of hardcoded repo.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GITEA_API_URL` | `https://git.softuniq.eu/api/v1` | Gitea API endpoint |
| `GITEA_TOKEN` | - | Gitea API token (PREFERRED) |
| `GITEA_USER` | - | Gitea username (fallback for Basic Auth) |
| `GITEA_PASS` | - | Gitea password (fallback for Basic Auth) |
| `GITEA_TARGET_REPO` | auto-detect | Override target project |
| `TARGET_URL` | `http://localhost:3000` | URL for testing |
| `PIXELMATCH_THRESHOLD` | `0.05` | Visual diff tolerance |

Auth resolution: `GITEA_TOKEN` → `GITEA_USER+GITEA_PASS` → `ValueError`. See `.kilo/shared/gitea-auth.md`.

## Quick Reference

```bash
# Pipeline for issue
/pipeline 42

# Laravel app
/laravel project_name

# WordPress plugin
/wordpress plugin_name

# Agent statistics
bun run agent:stats

# Evolution dashboard
bun run sync:evolution
bun run evolution:open

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

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