personamanagmentlayer__pcl/docs/PROJECT-STRUCTURE.md

# PCL Project Structure

This document describes the organization of the PCL project directory.

## Root Directory (Professional & Clean)

The root directory contains only essential project files:

```
pcl/
├── README.md              # Main project documentation
├── CHANGELOG.md           # Version history
├── CONTRIBUTING.md        # Contribution guidelines
├── QUICKSTART.md          # Quick start guide
├── LICENSE                # Apache 2.0 license
├── LICENSE-DOCS           # Documentation license
├── NOTICE                 # Copyright notices
├── package.json           # NPM package configuration
├── package-lock.json      # Dependency lock file
├── tsconfig.json          # TypeScript configuration
├── vitest.config.ts       # Test configuration
└── .editorconfig          # Editor configuration
```

## Documentation (`docs/`)

All project documentation is organized in the `docs/` directory:

```
docs/
├── api/                   # API documentation
│   ├── PARSER.md
│   ├── SEMANTIC.md
│   ├── CODEGEN.md
│   └── REGISTRY-SYSTEM.md
├── guides/                # User guides
│   ├── GETTING-STARTED.md
│   ├── VSCODE-SETUP.md
│   ├── QUICK-START-LOCAL.md
│   └── JSON-FILE-BACKEND.md
├── reference/             # Language reference
│   ├── LANGUAGE.md
│   └── ERROR-CODES.md
├── registry/              # Registry-specific documentation (NEW)
│   ├── DATABASE-FREE-REGISTRY.md
│   ├── REGISTRY-CHEATSHEET.md
│   └── TEST-RESULTS.md
└── changelog/             # Detailed changelogs (NEW)
    └── CHANGELOG-2026-01-18.md
```

## Source Code (`src/`)

```
src/
├── grammar/               # Language grammar
├── types/                 # Core type definitions
├── ast/                   # AST node types
├── lexer/                 # Tokenizer
├── parser/                # Parser implementation
├── semantic/              # Semantic analysis
├── runtime/               # Execution engine
├── registry/              # Registry system
│   ├── backends/
│   │   ├── memory.ts
│   │   ├── json-file.ts   # Database-free backend
│   │   ├── sqlite.ts
│   │   └── postgresql.ts
│   ├── manager.ts
│   └── interfaces.ts
├── compiler/              # Code generators
├── stdlib/                # Standard library
└── cli/                   # Command-line interface
    └── commands/
        └── registry/      # Registry CLI commands
```

## Examples (`docs/examples/`)

```
docs/examples/
      ├── tutorials/             # Tutorial examples
      │   ├── 01-first-persona/
      │   ├── 02-teams/
      │   ├── 03-workflows/
      │   ├── 04-real-app/
      │   ├── 05-integration/
      │   └── 06-advanced/
      └── personas/              # Example personas (NEW)
          └── test-persona.pcl
```

## Tests (`tests/`)

```
tests/
├── unit/                  # Unit tests
├── integration/           # Integration tests
└── fixtures/              # Test fixtures
```

## Configuration & Governance

```
.github/                   # GitHub configuration
├── workflows/             # CI/CD workflows
└── copilot-instructions.md

.vscode/                   # VS Code workspace
├── settings.json
├── extensions.json
└── README.md

.roadmap/                  # Project planning
├── ROADMAP.md
├── TODO.md
├── status/
│   └── CURRENT-STATUS.md
└── decisions/

GOVERNANCE/                # Governance documents
├── PCL_GOVERNANCE.md
├── PCL_SECURITY_MODEL.md
└── ...

SPEC/                      # Language specifications
├── PCL_SPEC_v1.md
└── ...

CORE/                      # Core concepts
└── ...

REF/                       # Reference materials
└── ...
```

## Build Output (`dist/`)

Generated by the build process (not in version control):

```
dist/
├── cli/
│   └── index.js
├── index.js
└── chunk-*.js
```

## Changes from Previous Structure

### Moved Files

1. **Registry Documentation** → `docs/registry/`
   - `DATABASE-FREE-REGISTRY.md`
   - `REGISTRY-CHEATSHEET.md`
   - `TEST-RESULTS.md`

2. **Detailed Changelogs** → `docs/changelog/`
   - `CHANGELOG-2026-01-18.md`

3. **Example Personas** → `examples/personas/`
   - `test-persona.pcl`

### Benefits of New Structure

✅ **Professional Root** - Only essential files visible at top level
✅ **Better Organization** - Related docs grouped together
✅ **Easy Navigation** - Clear folder hierarchy
✅ **Scalable** - Easy to add new documentation
✅ **Standard** - Follows best practices for open source projects

## Quick Access Links

### For Users

- [README](../README.md) - Start here
- [Quick Start](QUICKSTART.md) - Get running in 5 minutes
- [Database-Free Registry](docs/registry/DATABASE-FREE-REGISTRY.md) - No database needed!
- [Registry Cheatsheet](docs/registry/REGISTRY-CHEATSHEET.md) - Quick command reference

### For Developers

- [Contributing Guide](../CONTRIBUTING.md)
- [VS Code Setup](guides/VSCODE-SETUP.md)
- [API Documentation](api/)
- [Test Results](registry/TEST-RESULTS.md)

### For Contributors

- [Roadmap](.roadmap/ROADMAP.md)
- [Current Status](.roadmap/status/CURRENT-STATUS.md)
- [Governance](GOVERNANCE/)
- [Specifications](SPEC/)

---

_Last Updated: 2026-01-18_
_Structure Version: 2.0_