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 - Start here
• Quick Start - Get running in 5 minutes
• Database-Free Registry - No database needed!
• Registry Cheatsheet - Quick command reference

For Developers

• Contributing Guide
• VS Code Setup
• API Documentation
• Test Results

For Contributors

• Roadmap
• Current Status
• Governance
• Specifications

---

Last Updated: 2026-01-18 Structure Version: 2.0