Project Structure Metadata Guidelines

Overview

This document defines how Dart and Flutter projects are represented as metadata for automated build, documentation, and testing workflows. It provides a generic, reusable structure applicable to any Dart/Flutter project or multi-project workspace.

For detailed information about the Workspace Analyzer tool and its configuration options, see tom_ai/devops/tom_build/README.md.

Where the structure is written down

It is not written down. The directory tree is the structure, and reading it is how a reader or a tool learns the layout: a project is a folder with a pubspec.yaml, its parts and modules are its subfolders, its documentation is its doc/. The rules below say how to recognise each of those; they do not describe a manifest, and no manifest is to be consulted in their place.

The build tooling maintains its own generated inputs for mechanical builds. Those are the build system's, documented with it in tom_ai/devops/tom_build/README.md, and are not a source a reader or an AI session should be reading the workspace from.

Structural Hierarchy

Workspace
  └── Projects (one or more)
       └── Parts (optional, logical groupings)
            └── Modules (feature-specific implementations)
                 └── Subfolders (nested subdirectories, arbitrary depth)
  • Workspace: Top-level container (single project or multiple related projects)
  • Project: Individual package, application, or server
  • Parts: Logical subdivisions within a project (e.g., core, client, server, shared)
  • Modules: Feature-specific implementations within a part or project
  • Subfolders: Nested subdirectories within modules (supports arbitrary depth)

Workspace Structure

A workspace represents the root directory containing one or more related Dart/Flutter projects.

Important: Only Dart/Flutter projects (directories with pubspec.yaml) are included in metadata. Directories without pubspec.yaml are ignored and do not appear in .tom_metadata/.

Single-Project Workspace

  • Contains one pubspec.yaml at root
  • Project root is workspace root
  • Typical for standalone packages or applications

Multi-Project Workspace

  • Contains multiple subdirectories, each with its own pubspec.yaml
  • Common for monorepos with related projects
  • Examples: client + server, core + templates, multiple packages
  • Non-Dart directories are excluded from metadata (e.g., tom_ai_build/, tom_vscode_extension/)

Test Projects (zom_ prefix)

  • Projects and folders starting with zom_ are for test purposes only
  • Used to test build tools, workspace analyzers, and code generators
  • Should not be included in production builds or documentation
  • Example: zom_test_standalone, zom_test_flutter, zom_test_package

Workspace Components

  • Projects: One or more Dart/Flutter projects (must have pubspec.yaml)
  • Workspace Documentation: README.md at workspace root (introduction, overview)
  • Shared Configuration: Workspace-level settings (optional)
  • Workspace Assets: Shared resources across projects (optional)
  • Non-project directories: Ignored in metadata generation

Build Configuration Metadata

The workspace analyzer generates comprehensive build configuration for each project, enabling mechanical (no-AI) build automation. Configuration is resolved using a three-level hierarchy:

1. Auto-detected defaults: Built-in defaults per project type 2. Workspace-level overrides: applied to every project in the workspace 3. Project-level overrides: applied to one project

Build Configuration Tags

TagPurposeExample
build-after Dependencies (projects that must build first) [tom_core, tom_reflection]
build-order Workspace-level topological build order [lib_a, lib_b, app_c]
features Auto-detected project capabilities has-reflection: true
build Build commands and configuration commands, pre-build, output
run Run commands (for apps and CLIs) commands, docker
deploy Deployment configuration type, dockerfile, platforms

Feature Flags

The analyzer auto-detects project features:

  • has-reflection: Project uses code generation (*.g.dart, *.reflection.dart)
  • has-build-runner: Project has build.yaml configuration
  • has-native-deps: Project uses FFI or has native code
  • has-assets: Project has assets/ or fonts/ directories
  • has-docker: Project has Dockerfile or docker-compose.yml
  • publishable: Project can be published (not marked publish_to: none)
  • has-tests: Project has test directory with *_test.dart files
  • has-examples: Project has example directory

Build Order

The build-order tag at the workspace level provides the topologically sorted list of projects, respecting dependencies. Projects with no dependencies come first.

For detailed configuration examples, see tom_ai/devops/tom_build/README.md.

Project Types and Structure Rules

1. Package Library Project (dart_package)

  • Type: dart_package
  • Description: Reusable Dart package library
  • Detection: Has pubspec.yaml, no bin/ directory, not a Flutter project
  • Structure:
  • lib/ - Public API exports (top-level .dart files)
  • lib/src/ - Implementation organized into parts
  • example/ - Usage examples
  • test/ - Test suites
  • doc/ or doc/ - Documentation directory (optional)

Source Organization:

  • Package Module: Top-level files in lib/ (e.g., tom_core.dart, tom_client.dart)
  • Metadata: package.module.yml
  • Parts: Subdirectories in lib/src/ (e.g., tombase/, tomclient/, tomserver/)
  • Each part has: {part}.part.yml and {part}.module.yml
  • Part-level files go in the part's module
  • Subdirectories become modules: modules/{module}.module.yml
  • Subdirectories of modules become potentially nested subfolders

2. Flutter Application Project (flutter_app)

  • Type: flutter_app
  • Description: Flutter mobile/desktop/web application
  • Detection: Has pubspec.yaml with sdk: flutter dependency
  • Structure:
  • lib/ - Application source with top-level files and subdirectories
  • assets/ - Images, fonts, configuration files
  • test/ - Unit and widget tests
  • Platform directories: android/, ios/, linux/, macos/, web/, windows/

Source Organization:

  • App Module: Top-level files in lib/ (e.g., main.dart, 00_main.dart)
  • Metadata: {project}.module.yml
  • Parts: Direct subdirectories in lib/ (e.g., uam/, features/, screens/)
  • Each part has: {part}.part.yml and {part}.module.yml
  • Part-level files go in the part's module
  • Subdirectories become modules: modules/{module}.module.yml
  • Subdirectories of modules become potentially nested subfolders

3. Console/CLI Application Project (dart_console)

  • Type: dart_console
  • Description: Dart console or CLI application
  • Detection: Has pubspec.yaml with both bin/ AND lib/ directories. The bin/ directory is the key indicator that distinguishes this from a dart_package. Even if empty, the bin/ directory should be preserved (use .gitkeep) to maintain project type detection.
  • Structure:
  • bin/ - Executable entry points and implementation
  • lib/ - Shared implementation (optional)
  • assets/ - Configuration, static files
  • test/ - Server tests
  • database_migrations/ - Database scripts (optional)
  • deployment/ - Cloud deployment scripts (.sh) & configuration templates
  • docker/ - Docker-specific configurations (pubspec overrides, datasource configs)
  • doc/ - Project-specific documentation (e.g. API docs, guides)

Source Organization:

  • Always has two parts: bin/ and lib/ (even if lib is minimal)
  • bin part:
  • Metadata: bin.part.yml and bin.module.yml
  • Top-level files in bin/ go in bin's module
  • bin/src/ subdirectories become modules: modules/{module}.module.yml
  • Subdirectories of modules become potentially nested subfolders
  • lib part:
  • Metadata: lib.part.yml
  • lib/src/ subdirectories become modules: modules/{module}.module.yml
  • Subdirectories of modules become potentially nested subfolders

4. VS Code Extension Project (vscode_extension)

  • Type: vscode_extension
  • Description: Visual Studio Code extension (TypeScript)
  • Detection: Has package.json with engines.vscode field
  • Structure:
  • src/ - TypeScript source files
  • out/ or dist/ - Compiled output (ignored)
  • package.json - Extension manifest with contributes, activationEvents
  • tsconfig.json - TypeScript configuration

Source Organization:

  • Extension Module: Top-level .ts files in src/ (e.g., extension.ts)
  • Parts: Direct subdirectories in src/ (e.g., commands/, providers/)
  • Each part has sources and optional subfolders
  • Subdirectories become modules with nested subfolders support

Example (tom_vscode_extension):

src/
  extension.ts           → extensionModule sources
  commands/              → commands part
    registerCommands.ts
    openFile.ts
  providers/             → providers part
    treeProvider.ts
    completionProvider.ts

5. TypeScript Project (typescript)

  • Type: typescript
  • Description: Plain TypeScript/Node.js project
  • Detection: Has package.json AND tsconfig.json, but NO engines.vscode
  • Structure:
  • src/ - TypeScript source files
  • dist/ or build/ - Compiled output (ignored)
  • package.json - npm package manifest
  • tsconfig.json - TypeScript configuration

Source Organization:

  • Main Module: Top-level .ts files in src/
  • Parts: Direct subdirectories in src/
  • Subdirectories become modules with nested subfolders support

6. JavaScript Project (javascript)

  • Type: javascript
  • Description: Plain JavaScript/Node.js project
  • Detection: Has package.json, but NO tsconfig.json and NO engines.vscode
  • Structure:
  • src/ - JavaScript source files (or project root)
  • dist/ or build/ - Build output (ignored)
  • package.json - npm package manifest

Source Organization:

  • Main Module: Top-level .js files in src/ (or project root if no src/)
  • Parts: Direct subdirectories in src/
  • Subdirectories become modules with nested subfolders support

7. Java Project (java)

  • Type: java
  • Description: Java project (Maven or Gradle)
  • Detection: (Has pom.xml (Maven) OR build.gradle/build.gradle.kts (Gradle)) OR ( Has *.java files in folder /src or it's subfolders)
  • Structure:
  • src/main/java/ - Java source files
  • src/test/java/ - Test source files
  • pom.xml or build.gradle - Build configuration

Source Organization:

  • Main Module: Top-level .java files in source root
  • Parts: Package directories in src/main/java/
  • Subdirectories become modules following package hierarchy
  • Supports nested subfolders for deep package structures

Example (Maven project):

src/main/java/
  com/example/
    app/                 → app part
      Application.java
      config/            → config module
        AppConfig.java
      services/          → services module
        UserService.java

Project Type Detection Algorithm

Projects are identified by configuration files. Detection order is important:

def detect_project_type(project_path):
    """
    Determine project type based on configuration files and folder structure.
    Detection order matters - more specific types checked first.
    """
    has_pubspec = exists(project_path + "/pubspec.yaml")
    has_package_json = exists(project_path + "/package.json")
    has_tsconfig = exists(project_path + "/tsconfig.json")
    has_pom_xml = exists(project_path + "/pom.xml")
    has_build_gradle = exists(project_path + "/build.gradle") or exists(project_path + "/build.gradle.kts")
    
    # 1. Dart/Flutter projects (pubspec.yaml)
    if has_pubspec:
        has_bin = exists(project_path + "/bin")
        has_lib = exists(project_path + "/lib")
        has_lib_src = exists(project_path + "/lib/src")
        
        if has_bin and has_lib:
            return "dart_console"
        elif has_lib_src:
            return "dart_package"
        elif has_lib and not has_bin:
            return "flutter_app"
        else:
            return "dart_package"
    
    # 2. Java projects (Maven or Gradle)
    if has_pom_xml or has_build_gradle:
        return "java"
    
    # 3. Node.js/TypeScript projects (package.json)
    if has_package_json:
        # Check for VS Code extension
        package_content = read_json(project_path + "/package.json")
        if "engines" in package_content and "vscode" in package_content["engines"]:
            return "vscode_extension"
        
        # TypeScript project (has tsconfig.json)
        if has_tsconfig:
            return "typescript"
        
        # Plain JavaScript project
        return "javascript"
    
    return None  # Not a recognized project

def is_project(path):
    """A directory is a project if it has a recognized configuration file."""
    return (exists(path + "/pubspec.yaml") or
            exists(path + "/package.json") or
            exists(path + "/pom.xml") or
            exists(path + "/build.gradle") or
            exists(path + "/build.gradle.kts"))

def scan_workspace(workspace_root):
    """
    Find all projects in workspace.
    Includes Dart, Java, TypeScript, JavaScript, and VS Code extensions.
    """
    projects = []
    
    # Check if workspace root is a project
    if is_project(workspace_root):
        projects.append(workspace_root)
    
    # Check subdirectories
    for subdir in list_directories(workspace_root):
        subdir_path = workspace_root + "/" + subdir
        if is_project(subdir_path):
            projects.append(subdir_path)
    
    return projects

Detection Rules Summary:

Config FileAdditional CheckProject Type
pubspec.yaml has bin/ AND lib/ dart_console
pubspec.yaml has lib/src/ (no bin/) dart_package
pubspec.yaml has lib/ only (no bin/, no lib/src/) flutter_app
pom.xml or build.gradle-java
package.json has engines.vscode vscode_extension
package.json has tsconfig.json typescript
package.jsonno tsconfig, no vscodejavascript

Note: For dart_console projects, the bin/ directory is the key differentiator. Even if empty, preserve it with a .gitkeep file to maintain correct project type detection.

Detection Order (first match wins):

1. Dart/Flutter projects (pubspec.yaml) 2. Java projects (pom.xml or build.gradle) 3. VS Code extensions (package.json with engines.vscode) 4. TypeScript projects (package.json + tsconfig.json) 5. JavaScript projects (package.json only)

Source File Extensions by Type:

Project TypeFile ExtensionSource Folder
dart_package, dart_console, flutter_app .dart lib/, bin/
vscode_extension, typescript .ts src/
javascript.jssrc/
java.javasrc/main/java/

Documentation Structure

Documentation exists at multiple levels in the hierarchy:

Workspace Documentation

  • README.md: Workspace introduction, overview of projects, getting started
  • Location: Workspace root directory
  • Purpose: High-level overview for multi-project workspaces

Project Documentation

  • README.md: Project introduction, summary, quick start
  • Location: Project root directory
  • Purpose: Overview of what the project does, installation, basic usage
  • Additional Files (optional):
  • CHANGELOG.md - Version history and changes
  • LICENSE - License information
  • CONTRIBUTING.md - Contribution guidelines
  • doc/ or doc/ - Documentation directory containing:
  • Architecture documentation
  • API guides
  • Tutorials
  • Coding guidelines
  • Testing guidelines

Part Documentation

  • {part_name}.md: Part overview and architecture
  • Location: Part directory (e.g., lib/src/core/core.md)
  • Purpose: Explain the part's purpose, list modules, describe relationships
  • Content: Overview, module list, common patterns, dependencies

Module Documentation

  • {module_name}.md: Module-specific documentation
  • Location: Module directory (e.g., lib/src/core/logging/logging.md)
  • Purpose: Detailed API documentation, usage examples, best practices
  • Content: API reference, usage examples, configuration, common scenarios

Subfolders (Nested Hierarchy)

Modules can contain nested subfolders to arbitrary depth. Each subfolder follows the same structure as a module:

  • name: Folder name (lowercase, snake_case)
  • displayName: Human-readable name
  • sources: Direct .dart files in the folder
  • subfolders: Nested subdirectories (recursive)

Subfolder Example

modules:
  - name: analysis
    displayName: Analysis
    sources: [analysis.dart]
    subfolders:
      - name: parsers
        displayName: Parsers
        sources: [parsers.dart]
        subfolders:
          - name: yaml
            displayName: Yaml
            sources: [yaml_parser.dart, yaml_utils.dart]
          - name: dart
            displayName: Dart
            sources: [dart_parser.dart]
      - name: validators
        displayName: Validators
        sources: [validator.dart]

This corresponds to the folder structure:

analysis/
  analysis.dart
  parsers/
    parsers.dart
    yaml/
      yaml_parser.dart
      yaml_utils.dart
    dart/
      dart_parser.dart
  validators/
    validator.dart

Parts (Logical Subdivisions)

Parts are optional logical groupings within a project's source folder. A project may have:

  • No Parts: Modules directly in source folder (e.g., lib/src/module_a/, lib/src/module_b/)
  • Multiple Parts: Organized by purpose (e.g., lib/src/core/, lib/src/client/, lib/src/server/)

Part and Module Identification

Parts and modules are identified based on project type and directory structure:

Package Projects (dart_package)

  • Package Module: Top-level .dart files in lib/ directory
  • Metadata file: package.module.yml in project root
  • Parts: Subdirectories in lib/src/
  • Each part directory becomes a part
  • Metadata: {part}/ directory with {part}.part.yml
  • Part Modules: Files directly in part directory
  • Metadata: {part}.module.yml alongside {part}.part.yml
  • Submodules: Subdirectories within a part
  • Metadata: {part}/modules/{module}.module.yml

Example (tom_core):

lib/
  tom_core.dart              → package.module.yml
  tom_client.dart            → package.module.yml  
  tom_server.dart            → package.module.yml
  src/
    tombase/                 → tombase.part.yml + tombase.module.yml
      api/                   → modules/api.module.yml
      logging/               → modules/logging.module.yml
    tomclient/               → tomclient.part.yml + tomclient.module.yml
      services/              → modules/services.module.yml

Flutter Applications (flutter_app)

  • App Module: Top-level .dart files in lib/ directory
  • Metadata file: {project}.module.yml in project root
  • Parts: Direct subdirectories in lib/
  • Each subdirectory becomes a part
  • Metadata: {part}/ directory with {part}.part.yml
  • Part Modules: Files directly in part directory
  • Metadata: {part}.module.yml alongside {part}.part.yml
  • Submodules: Subdirectories within a part
  • Metadata: {part}/modules/{module}.module.yml

Example (tom_uam_client):

lib/
  main.dart                  → tom_uam_client.module.yml
  00_main.dart               → tom_uam_client.module.yml
  uam/                       → uam.part.yml + uam.module.yml
    application.dart         → uam.module.yml
    pages/                   → modules/pages.module.yml
    widgets/                 → modules/widgets.module.yml

Console Applications (dart_console)

  • Always has two parts: bin and lib
  • bin part:
  • Top-level files in bin/ → bin.module.yml
  • bin/src/ subdirectories → bin/modules/{module}.module.yml
  • lib part:
  • lib/src/ subdirectories → lib/modules/{module}.module.yml

Example (tom_uam_server):

bin/
  aa_server_start.dart       → bin.module.yml
  ab_server_runtime_definition.dart → bin.module.yml
  src/
    startup/                 → bin/modules/startup.module.yml
lib/
  src/
    services/                → lib/modules/services.module.yml
    models/                  → lib/modules/models.module.yml

Detection Rules Summary

1. dart_package: - Has parts/ metadata folder - Parts are from lib/src/ subdirectories - Has package.module.yml for lib-level files

2. flutter_app: - Has parts/ metadata folder - Parts are from lib/ subdirectories - Has {project}.module.yml for lib-level files

3. dart_console: - Always has parts/ metadata folder with bin/ and lib/ - No project-level module (all code is in parts)

4. All types: - Parts can have both .part.yml and .module.yml files - Part .module.yml contains metadata for files directly in the part directory - Submodules go in modules/ subdirectory

Real-World Examples from Workspace

Example 1: tom_core (dart_package)

Source Structure:

tom_core/
  lib/
    tom_core.dart              # Public API
    tom_client.dart            # Public API
    tom_server.dart            # Public API
    src/
      tombase/                 # Part
        api/                   # Module
        beanlocator/           # Module
        logging/               # Module
        settings/              # Module
      tomclient/               # Part
        (modules...)
      tomserver/               # Part
        (modules...)

Metadata Structure:

.tom_metadata/projects/tom_core/
├── tom_core.project.yml       # Project metadata
├── package.module.yml         # Module for tom_core.dart, tom_client.dart, tom_server.dart
└── parts/
    ├── tombase/
    │   ├── tombase.part.yml
    │   ├── tombase.module.yml # Files directly in lib/src/tombase/
    │   └── modules/
    │       ├── api.module.yml
    │       ├── beanlocator.module.yml
    │       ├── logging.module.yml
    │       └── settings.module.yml
    ├── tomclient/
    │   ├── tomclient.part.yml
    │   ├── tomclient.module.yml
    │   └── modules/
    │       └── (client modules...)
    └── tomserver/
        ├── tomserver.part.yml
        ├── tomserver.module.yml
        └── modules/
            └── (server modules...)

Example 2: tom_uam_client (flutter_app)

Source Structure:

tom_uam_client/
  lib/
    00_main.dart               # Entry point
    01_client_runtime_definition.dart
    02_environment_initialization.dart
    03_startup_login.dart
    04_remote_logging.dart
    main_dev.dart
    main_int.dart
    main_prod.dart
    uam/                       # Feature part
      application.dart
      global_settings.dart
      pages/                   # Submodule
      widgets/                 # Submodule
      utils/                   # Submodule

Metadata Structure:

.tom_metadata/projects/tom_uam_client/
├── tom_uam_client.project.yml
├── tom_uam_client.module.yml  # Module for lib-level files
└── parts/
    └── uam/
        ├── uam.part.yml
        ├── uam.module.yml          # Files directly in lib/uam/
        └── modules/
            ├── pages.module.yml
            ├── widgets.module.yml
            └── utils.module.yml

Example 3: tom_uam_server (dart_console)

Source Structure:

tom_uam_server/
  bin/
    aa_server_start.dart
    ab_server_runtime_definition.dart
    aca_log_levels.dart
    (more bin-level files...)
    src/
      (server startup modules...)
  lib/
    src/
      services/                # Module
      models/                  # Module
      (more lib modules...)

Metadata Structure:

.tom_metadata/projects/tom_uam_server/
├── tom_uam_server.project.yml
└── parts/
    ├── bin/
    │   ├── bin.part.yml
    │   ├── bin.module.yml          # bin-level .dart files
    │   └── modules/
    │       └── (bin/src modules...)
    └── lib/
        ├── lib.part.yml
        └── modules/
            ├── services.module.yml
            ├── models.module.yml
            └── (other lib/src modules...)

Structure Comparison

Project TypeTop-level ModulePartsModule Organization
dart_package package.module.yml From lib/src/ Parts have .part.yml + .module.yml + modules/
flutter_app {project}.module.yml From lib/ subdirs Parts have .part.yml + .module.yml + modules/
dart_console None Always bin + lib Parts have .part.yml + .module.yml + modules/

Module Structure

Each module is a directory containing related functionality.

Module Components

  • Source Files: *.dart files implementing functionality
  • Documentation: {module_name}.md documentation file (typically in module directory)
  • Examples: Implementation examples (location varies by project structure)
  • Tests: Unit/integration tests (typically in test/ mirroring source structure)
  • Assets: Module-specific resources (optional)

Module Naming Conventions

  • Directory name: snake_case (e.g., user_authentication/, data_storage/)
  • Documentation file: {module_name}.md (e.g., user_authentication.md)
  • Test file: {module_name}_test.dart (e.g., user_authentication_test.dart)

Asset and Resource Files

Projects may include various asset and resource types:

Common Asset Types

1. Configuration Files - JSON: *.json (e.g., config.json, settings.json) - YAML: *.yaml (e.g., application.yaml) - Environment: .env, .env.local

2. Static Resources - Images: *.png, *.jpg, *.svg - Fonts: *.ttf, *.otf - Icons: Platform-specific icon sets

3. Data Files - Localization: *.arb, i18n/*.json - Templates: *.html, *.md - Sample data: *.json, *.csv

Asset Location Patterns

Flutter Apps:

assets/
  images/
  fonts/
  config/
  i18n/

Server Apps:

assets/
  static/           # Served static files
  templates/        # Email/HTML templates
  config/          # Configuration files
assets_client/     # Client-facing assets (optional)

Packages:

lib/assets/        # Package-bundled assets
example/assets/    # Example assets

Project Files

Essential Files

  • pubspec.yaml - Package dependencies and metadata
  • analysis_options.yaml - Dart analyzer configuration
  • build.yaml - Build configuration (when using code generation)
  • README.md - Project documentation
  • CHANGELOG.md - Version history
  • LICENSE - License information

Configuration Files

  • .gitignore - Git exclusion rules
  • .env - Environment variables (server projects)
  • docker-compose.yaml - Docker configuration (server projects)
  • Dockerfile - Container definition (server projects)

Excluded Directories and Files

The following should be excluded from metadata and processing:

IDE and Editor Directories

  • .idea/ - IntelliJ IDEA configuration
  • .vscode/ - Visual Studio Code configuration
  • *.iml - IntelliJ module files

Version Control

  • .git/ - Git repository data

Build Artifacts

  • .dart_tool/ - Dart build tools cache
  • build/ - Build output
  • .flutter-plugins-dependencies - Flutter plugin state
  • .metadata - Flutter metadata cache

System Files

  • .DS_Store - macOS Finder metadata
  • Thumbs.db - Windows thumbnail cache

Lock Files (Optional Exclusion)

  • pubspec.lock - Dependency lock file (include for reproducibility)

Backup and Temporary

  • backup/ - Backup directories
  • *~ - Temporary files
  • *.bak - Backup files

Metadata Structure

Metadata is organized in a directory tree mirroring the workspace structure. This approach provides:

  • Incremental Loading: Load only needed metadata for specific tasks
  • Scalability: Handles large workspaces without massive single files
  • Natural Navigation: Metadata structure matches code organization
  • Easier Updates: Update individual components without rewriting entire structure

File Naming Convention: Double Extension

All metadata files use double extensions to indicate both the entity type and file format:

  • {name}.project.yml - Project metadata
  • {name}.part.yml - Part metadata
  • {name}.module.yml - Module metadata
  • {workspace_root}.workspace.yml - Workspace metadata
  • {workspace_root}.index.yml - Index file (optional)
  • package.module.yml - Files at lib/ level (dart_package only)
  • {project}.module.yml - Files at lib/src/ level (dart_package) or lib/ level (flutter_app)

The double extension makes it explicit which schema the file follows, improving tooling and clarity.

Project Type Structures

Package Project (dart_package)

Structure: Has lib/ folder with top-level files and lib/src/ for implementation

Metadata Organization:

.tom_metadata/projects/my_package/
├── my_package.project.yml          # Project metadata
├── package.module.yml              # Module for lib/ level files
├── my_package.module.yml           # Module for lib/src/ level files
└── parts/                          # Parts from lib/src/ subdirectories
    ├── core/
    │   ├── core.part.yml           # Part metadata
    │   ├── core.module.yml         # Module for part-level files (if any)
    │   └── modules/
    │       ├── logging.module.yml
    │       └── config.module.yml
    └── client/
        ├── client.part.yml
        ├── client.module.yml
        └── modules/
            └── ui.module.yml

Flutter Application (flutter_app)

Structure: Has lib/ folder with top-level files and subdirectories/modules

Metadata Organization:

.tom_metadata/projects/my_app/
├── my_app.project.yml              # Project metadata
├── my_app.module.yml               # Module for lib/ level files (main.dart, etc.)
└── parts/                          # Parts/modules from lib/ subdirectories
    └── uam/
        ├── uam.part.yml            # Part metadata
        ├── uam.module.yml          # Module for uam/ level files
        └── modules/                # Submodules
            ├── pages.module.yml
            ├── widgets.module.yml
            └── utils.module.yml

Console/CLI Application (dart_console)

Structure: Has bin/ for executables and lib/ for implementation

Metadata Organization:

.tom_metadata/projects/my_server/
├── my_server.project.yml           # Project metadata
└── parts/
    ├── bin/
    │   ├── bin.part.yml            # Part metadata for bin/
    │   ├── bin.module.yml          # Module for bin/ level files
    │   └── modules/                # Submodules in bin/src/
    │       └── startup.module.yml
    └── lib/
        ├── lib.part.yml            # Part metadata for lib/
        ├── lib.module.yml          # Module for lib/ level files
        └── modules/                # Modules in lib/src/
            ├── services.module.yml
            └── models.module.yml

Metadata Directory Organization

workspace_root/
├── .tom_metadata/
│   ├── {workspace_root}.workspace.yml          # Workspace-level metadata
│   ├── {workspace_root}.index.yml              # Quick reference index (optional)
│   └── projects/
│       ├── dart_package/                       # Package (dart_package)
│       │   ├── dart_package.project.yml
│       │   ├── package.module.yml              # lib/ level files
│       │   ├── dart_package.module.yml         # lib/src/ level files
│       │   └── parts/
│       │       ├── core/
│       │       │   ├── core.part.yml
│       │       │   ├── core.module.yml         # Part-level files
│       │       │   └── modules/
│       │       │       ├── api.module.yml
│       │       │       ├── logging.module.yml
│       │       │       └── config.module.yml
│       │       └── client/
│       │           ├── client.part.yml
│       │           ├── client.module.yml
│       │           └── modules/
│       │               └── ui.module.yml
│       ├── flutter_app/                        # Flutter app (flutter_app)
│       │   ├── flutter_app.project.yml
│       │   ├── flutter_app.module.yml          # lib/ level files
│       │   └── parts/
│       │       └── features/
│       │           ├── features.part.yml
│       │           ├── features.module.yml     # Part-level files
│       │           └── modules/
│       │               ├── pages.module.yml
│       │               ├── widgets.module.yml
│       │               └── auth.module.yml
│       └── dart_console/                        # Server (dart_console)
│           ├── dart_console.project.yml
│           └── parts/
│               ├── bin/
│               │   ├── bin.part.yml
│               │   ├── bin.module.yml          # bin/ level files
│               │   └── modules/
│               │       └── startup.module.yml
│               └── lib/
│                   ├── lib.part.yml
│                   ├── lib.module.yml          # lib/ level files
│                   └── modules/
│                       ├── services.module.yml
│                       └── models.module.yml

Index File (Optional Quick Reference)

workspace_root/.tom_metadata/{workspace_root}.index.yml:

metadata_version: "1.0"
workspace_name: "my_workspace"
generated_at: "2026-01-04T10:30:00Z"

projects:
  - name: "core_package"
    type: "dart_package"
    has_parts: true
    
  - name: "client_app"
    type: "flutter_app"
    has_parts: false

Workspace Metadata Schema

workspace_root/.tom_metadata/{workspace_root}.workspace.yml:

workspace:
  name: "my_workspace"
  root_path: "/absolute/path/to/workspace"
  type: "single_project"  # single_project | multi_project
  
  documentation:
    readme: "README.md"
    additional:
      - "CONTRIBUTING.md"
      - "CODE_OF_CONDUCT.md"
  
  projects:
    - name: "core_package"
      path: "core_package"              # Directory relative to workspace root
      type: "dart_package"
      
    - name: "client_app"
      path: "client_app"                # Directory relative to workspace root
      type: "flutter_app"
      
    - name: "server_app"
      path: "server_app"                # Directory relative to workspace root
      type: "dart_console"
  
  shared_config:                        # Optional
    analysis_options: ".analysis_options.yaml"
    ide_config: ".vscode/"              # Directory

Project Metadata Schema

workspace_root/.tom_metadata/projects/{project_name}/{project_name}.project.yml:

project:
  name: "my_package"
  type: "dart_package"  # dart_package | flutter_app | dart_console
  root_path: "/absolute/path/to/project"
  relative_path: "my_package"           # Directory relative to workspace root
  package_name: "my_package"            # From pubspec.yaml
  
  source_folder: "lib/src"              # Directory, varies by project type
  has_parts: true                       # true if multi-part structure
  
  documentation:
    readme: "README.md"
    changelog: "CHANGELOG.md"
    license: "LICENSE"
    docs_folder: "doc"                  # Directory (optional)
    guidelines:                         # Optional
      coding: "doc/coding_guidelines.md"
      testing: "doc/testing_guidelines.md"
      documentation: "doc/documentation_guidelines.md"
  
  essential_files:
    - "pubspec.yaml"
    - "analysis_options.yaml"
    - "README.md"
  
  optional_files:
    - "build.yaml"                      # If using code generation
    - "CHANGELOG.md"
    - "LICENSE"
  
  # For multi-part projects (has_parts: true), include parts:
  parts:                                # Only present if has_parts: true
    - name: "core"
      path: "lib/src/core"              # Directory
      export_file: "lib/core.dart"      # Part export file (typically at lib level)
      # Note: Modules for this part are in .tom_metadata/projects/{project_name}/parts/core/modules/
      
    - name: "client"
      path: "lib/src/client"            # Directory
      export_file: "lib/client.dart"    # Part export file
      # Note: Modules for this part are in .tom_metadata/projects/{project_name}/parts/client/modules/
  
  # For single-part projects (has_parts: false), modules are listed here:
  # modules:                            # Only present if has_parts: false
  #   - name: "utils"
  #     path: "lib/src/utils"           # Directory
  #   - name: "services"
  #     path: "lib/src/services"        # Directory
  # Note: Module YAML files are in .tom_metadata/projects/{project_name}/modules/
  
  example_base_path: "example"          # Directory
  test_base_path: "test"                # Directory
  assets_path: "assets"                 # Directory (optional)

Part Metadata Schema

workspace_root/.tom_metadata/projects/{project_name}/parts/{part_name}/{part_name}.part.yml: 

part:
  name: "core"
  path: "lib/src/core"                  # Directory relative to project root
  parent_project: "my_package"
  
  export_file: "lib/core.dart"          # Part export file (optional but typical)
  export_pattern: |                     # How the export file exports this part
    // Export core functionality
    export 'src/core/logging/logger.dart';
    export 'src/core/config/settings.dart';
  
  documentation:
    overview: "lib/src/core/core.md"
    description: "Core functionality and utilities"
  
  modules:
    - name: "logging"
    - name: "configuration"
    - name: "utilities"
  # Note: Module YAML files are in .tom_metadata/projects/{project_name}/parts/{part_name}/modules/
  
  module_base_path: "lib/src/core"      # Directory
  example_path: "example/core"          # Directory (optional)
  test_path: "test/core"                # Directory (optional)

Module Metadata Schema

For part-level module (files in part directory): workspace_root/.tom_metadata/projects/{project_name}/parts/{part_name}/{part_name}.module.yml

For submodules (subdirectories in part): workspace_root/.tom_metadata/projects/{project_name}/parts/{part_name}/modules/{module_name}.module.yml

For project-level module (package or app top-level files): workspace_root/.tom_metadata/projects/{project_name}/package.module.yml (packages) workspace_root/.tom_metadata/projects/{project_name}/{project_name}.module.yml (apps) 

module:
  name: "authentication"
  path: "lib/src/core/authentication"   # Directory relative to project root
  part: "core"                          # null if single-part project
  parent_project: "my_package"
  
  files:                                # All source files in module
    - "auth_service.dart"
    - "token_manager.dart"
    - "credentials.dart"
    - "validators.dart"
  
  entry_point: "auth_service.dart"      # Main file (optional but recommended)
  
  export_file: "lib/authentication.dart"  # Module export file (optional, less common than part exports)
  export_pattern: |                       # If module has its own export
    export 'src/core/authentication/auth_service.dart';
    export 'src/core/authentication/credentials.dart';
  
  public_apis:                          # Optional: explicitly list public APIs
    classes:
      - "AuthService"
      - "TokenManager"
      - "Credentials"
    functions:
      - "validateCredentials"
  
  documentation:
    file: "authentication.md"
    path: "lib/src/core/authentication/authentication.md"
    description: "User authentication and authorization"
  
  example_path: "example/core/authentication"           # Directory (optional)
  example_files:                                        # Optional
    - "basic_auth_example.dart"
    - "oauth_example.dart"
    - "token_refresh_example.dart"
  
  test_path: "test/core/authentication_test.dart"       # Can be file or directory
  test_files:                                           # Optional (if directory)
    - "authentication_test.dart"
    - "token_manager_test.dart"
    - "credentials_test.dart"
  
  assets:                                               # Optional
    - "assets/config/auth_config.json"
  
  dependencies:
    internal:                                           # Other modules in project
      - module: "logging"
        part: "core"
      - module: "configuration"
        part: "core"
    external:                                           # External packages
      - "http"
      - "jwt_decoder"
      - "crypto"
  example_base_path: "example"    # Directory
  test_base_path: "test"          # Directory
  assets_path: "assets"           # Directory (optional)

Part Metadata Schema (Alternative)

part:
  name: "core"
  path: "lib/src/core"            # Directory
  parent_project: "my_package"
  
  documentation:
    overview: "lib/src/core/core.md"
    description: "Core functionality and utilities"
  
  modules:
    - "logging"
    - "configuration"
    - "utilities"
  
  module_base_path: "lib/src/core"      # Directory
  example_path: "example/core"          # Directory (optional)
  test_path: "test/core"                # Directory (optional)

Module Metadata Schema (Alternative)

module:
  name: "authentication"
  path: "lib/src/core/authentication"   # Directory
  part: "core"                          # null if single-part project
  parent_project: "my_package"
  
  source_files:
    - "auth_service.dart"
    - "token_manager.dart"
    - "credentials.dart"
  
  documentation:
    file: "authentication.md"
    path: "lib/src/core/authentication/authentication.md"
    description: "User authentication and authorization"
  
  example_path: "example/core/authentication"           # Directory (optional)
  example_files:                                        # Optional
    - "basic_auth_example.dart"
    - "oauth_example.dart"
  
  test_path: "test/core/authentication_test.dart"       # Can be file or directory
  test_files:                                           # Optional
    - "authentication_test.dart"
    - "token_manager_test.dart"
  
  assets:                                               # Optional
    - "assets/config/auth_config.json"
  
  api_export: "lib/core_api.dart"                      # Optional, for consolidated exports
  
  dependencies:
    internal:                                           # Other modules in project
      - "logging"
      - "configuration"
    external:                                           # External packages
      - "http"
      - "jwt_decoder"

Asset Metadata Schema

assets:
  base_path: "assets"             # Directory
  
  groups:
    - name: "images"
      path: "assets/images"       # Directory
      patterns:
        - "*.png"
        - "*.jpg"
        - "*.svg"
    
    - name: "fonts"
      path: "assets/fonts"        # Directory
      patterns:
        - "*.ttf"
        - "*.otf"
    
    - name: "config"
      path: "assets/config"       # Directory
      files:
        - "app_config.json"
        - "feature_flags.yaml"
    
    - name: "i18n"
      path: "assets/i18n"         # Directory
      patterns:
        - "*.arb"
        - "*.json"

Discovery Rules

Workspace Detection

1. Single-Project Workspace: - pubspec.yaml exists at root - No subdirectories with pubspec.yaml (except in standard locations like example/) - Workspace root = Project root

2. Multi-Project Workspace: - Multiple subdirectories contain pubspec.yaml - Each subdirectory is a separate project - May have workspace-level README.md

Detection Algorithm:

root_has_pubspec = exists("pubspec.yaml")
subdirs_with_pubspec = find_subdirectories_with_file("pubspec.yaml", 
                                                      exclude=["example", "test", ".dart_tool"])

if root_has_pubspec and subdirs_with_pubspec.isEmpty:
  workspace_type = "single_project"
  projects = [root_directory]
else if subdirs_with_pubspec.isNotEmpty:
  workspace_type = "multi_project"
  projects = subdirs_with_pubspec
  if root_has_pubspec:
    projects.add(root_directory)

Project Type Detection

Analyze pubspec.yaml and project structure:

# dart_package indicators:
dependencies:
  # No flutter dependency
environment:
  sdk: '>=3.0.0'

# flutter_app indicators:
dependencies:
  flutter:
    sdk: flutter
# Contains: android/, ios/, etc. directories

# dart_console indicators:
dependencies:
  shelf: ^1.0.0  # or similar server packages
# Contains: bin/ directory with server entry points

Source Folder Detection by Type

1. dart_package: - Primary: lib/src/ (directory) - Fallback: lib/ if no src/ subdirectory (directory)

2. flutter_app: - Primary: lib/ (directory) - No src/ convention typically used

3. dart_console: - Implementation: lib/src/ or lib/ (directory) - Entry points: bin/ (directory)

Part vs Module Detection

The structure is determined by checking for specific folders in the project's metadata location:

Detection Algorithm:

project_metadata_path = .tom_metadata/projects/{project_name}/

has_parts_folder = exists(project_metadata_path + "parts/")
has_modules_folder = exists(project_metadata_path + "modules/")

if has_parts_folder AND has_modules_folder:
  ERROR: "Invalid project structure - both 'parts/' and 'modules/' folders exist"
  
if has_parts_folder:
  has_parts = true
  # Metadata: .tom_metadata/projects/{project}/parts/{part}/modules/{module}.yaml
  for each part_dir in parts/:
    load part metadata from parts/{part}/{part}.yaml
    for each module in parts/{part}/modules/:
      load module metadata
      
else if has_modules_folder:
  has_parts = false
  # Metadata: .tom_metadata/projects/{project}/modules/{module}.yaml
  for each module in modules/:
    load module metadata
    
else:
  ERROR: "No structure folders found - expected 'parts/' or 'modules/'"

Note: The actual source code structure (lib/src/) may vary, but the metadata organization follows this strict folder convention for consistent detection and processing.

Module Discovery

For each potential module directory:

1. Identify source files: *.dart files (exclude *.g.dart, *.reflectable.dart) 2. Find documentation: Look for {module_name}.md in: - Module directory - Project doc/ or doc/ directory - Part doc/ or doc/ directory (if applicable) 3. Locate examples: Search in: - example/{part}/{module}/ (multi-part) - directory - example/{module}/ (single-part) - directory - example/samples/{part}/{module}/ (organized structure) - directory 4. Find tests: Look for: - test/{part}/{module}_test.dart - file - test/{module}_test.dart - file - test/{part}/{module}/ (directory of multiple test files)

Asset Discovery

1. Scan asset directories: assets/, lib/assets/, platform-specific directories 2. Parse pubspec.yaml for declared assets: 

   flutter:
     assets:
       - assets/images/         # Directory
       - assets/config/app_config.json  # File

3. Identify by pattern: Group by file extension or directory convention

Documentation Discovery

Workspace Level:

  • README.md at workspace root (required for multi-project workspaces)
  • CONTRIBUTING.md, CODE_OF_CONDUCT.md (optional)

Project Level:

  • README.md at project root (required)
  • CHANGELOG.md, LICENSE at project root (recommended)
  • doc/ or doc/ directory (optional)
  • Look for guideline files: *_guidelines.md, *_guide.md

Part Level:

  • {part_name}.md in part directory (e.g., lib/src/core/core.md)
  • Alternative: doc/{part_name}.md in project docs directory

Module Level:

  • {module_name}.md in module directory (primary location)
  • Alternative: doc/{part}/{module_name}.md or doc/{module_name}.md

Reference Projects for Context

When analyzing usage patterns, projects may reference:

  • Template projects: Sibling directories providing implementation patterns
  • Example implementations: Within project's example/ directory
  • Test suites: Usage demonstrated in tests
  • Documentation samples: Code snippets in markdown files

File Pattern Matching

Include Patterns:

  • **/*.dart - All Dart source files
  • **/*.md - All Markdown documentation
  • **/*.yaml - Configuration files
  • **/*.json - Data and configuration files
  • assets/**/* - Asset files
  • pubspec.yaml - Package manifest
  • README.md - Project documentation
  • CHANGELOG.md - Version history
  • LICENSE - License information

Exclude Patterns:

  • .dart_tool/** - Dart build tools cache
  • build/** - Build output directory
  • .git/** - Git repository data
  • .idea/** - IntelliJ IDEA configuration
  • .vscode/** - Visual Studio Code configuration
  • **/*.g.dart - Generated Dart files
  • **/*.reflectable.dart - Generated reflection files
  • **/*.freezed.dart - Generated freezed files
  • **/*.mocks.dart - Generated mock files
  • **/.DS_Store - macOS Finder metadata
  • **/Thumbs.db - Windows thumbnail cache
  • **/*.iml - IntelliJ module files
  • .flutter-plugins-dependencies - Flutter plugin state
  • .metadata - Flutter metadata cache
  • .packages - Legacy package configuration
  • pubspec.lock - Dependency lock (optional exclusion)

Platform-Specific Exclusions (Flutter):

  • android/build/** - Android build outputs
  • ios/Pods/** - iOS CocoaPods
  • ios/.symlinks/** - iOS symlinks
  • macos/Pods/** - macOS CocoaPods
  • windows/flutter/** - Windows Flutter engine
  • linux/flutter/** - Linux Flutter engine

Validation Rules

Workspace Validation

✅ Valid Single-Project Workspace:

  • pubspec.yaml at root
  • Valid project structure
  • README.md at root

✅ Valid Multi-Project Workspace:

  • Multiple subdirectories with pubspec.yaml
  • Each project has valid structure
  • README.md at workspace root (recommended)

⚠️ Warning Conditions:

  • Multi-project workspace without root README.md
  • Projects with inconsistent structure conventions
  • Missing shared configuration

Project Validation

✅ Required Elements:

  • Valid pubspec.yaml with name: and environment: fields
  • Source directory (lib/, bin/, or lib/src/) exists
  • At least one .dart file in source directory
  • README.md with project description

⚠️ Recommended Elements (warnings if missing):

  • analysis_options.yaml - Linter configuration
  • CHANGELOG.md - Version tracking
  • LICENSE - License information
  • test/ directory with tests
  • Documentation for public APIs

❌ Invalid Conditions:

  • Missing or malformed pubspec.yaml
  • No .dart files in source directory
  • Circular dependencies between modules
  • Invalid Dart syntax in source files

Part Validation (Multi-Part Projects)

✅ Valid Part:

  • Directory in source folder
  • Contains at least one module subdirectory
  • Module subdirectories contain .dart files

⚠️ Warning Conditions:

  • Part with only one module (consider flattening)
  • Empty part directory
  • No documentation file ({part_name}.md)

Module Validation

✅ Valid Module:

  • Directory in source folder (or part subdirectory)
  • Contains at least one .dart source file
  • Documentation file {module_name}.md exists (recommended)

⚠️ Warning Conditions:

  • No public classes/functions in module
  • Missing examples in example/ directory
  • Missing test file in test/ directory
  • Documentation doesn't cover all public APIs
  • Orphaned module (no imports from other parts of project)
  • Missing module documentation file

❌ Invalid Module:

  • Directory contains no .dart files
  • All .dart files are generated (.g.dart, etc.)
  • Module name conflicts with Dart reserved words

Documentation Validation

✅ Valid Documentation:

  • README.md exists at workspace and project roots
  • Module documentation files match module names
  • Documentation files are valid Markdown

⚠️ Warning Conditions:

  • Missing CHANGELOG.md for published packages
  • Missing LICENSE for public packages
  • Part has no documentation file
  • Outdated documentation (mentions removed APIs)
  • Missing code examples in documentation

❌ Invalid Documentation:

  • README.md is empty or placeholder text
  • Documentation references non-existent code
  • Malformed Markdown syntax

Asset Validation

✅ Valid Asset Configuration:

  • Assets declared in pubspec.yaml exist on filesystem
  • Asset paths are relative to project root
  • No duplicate asset declarations

⚠️ Warning Conditions:

  • Unused assets (declared but not referenced in code)
  • Large assets without compression
  • Missing asset variations (different resolutions, etc.)

❌ Invalid Asset Configuration:

  • Asset declared in pubspec.yaml but file doesn't exist
  • Invalid asset path format
  • Asset outside project directory

Example Project Structures

Single-Project Workspace (Single-Part Package)

my_package/                     # Workspace root = Project root
├── lib/
│   ├── my_package.dart         # Main export
│   └── src/                    # Source directory
│       ├── authentication/     # Module directory
│       │   ├── auth_service.dart
│       │   └── authentication.md
│       ├── database/           # Module directory
│       │   ├── db_connection.dart
│       │   └── database.md
│       └── utils/              # Module directory
│           ├── helpers.dart
│           └── utils.md
├── example/                    # Examples directory
│   ├── authentication/
│   │   └── auth_example.dart
│   └── database/
│       └── db_example.dart
├── test/                       # Tests directory
│   ├── authentication_test.dart
│   ├── database_test.dart
│   └── utils_test.dart
├── doc/                        # Documentation directory
│   ├── coding_guidelines.md
│   └── testing_guidelines.md
├── pubspec.yaml
├── analysis_options.yaml
├── README.md
├── CHANGELOG.md
└── LICENSE

Single-Project Workspace (Multi-Part Package)

framework/                      # Workspace root = Project root
├── lib/
│   ├── framework.dart          # Main export
│   ├── core.dart               # Part export
│   ├── client.dart             # Part export
│   └── src/                    # Source directory
│       ├── core/               # Part directory
│       │   ├── core.md         # Part documentation
│       │   ├── logging/        # Module directory
│       │   │   ├── logger.dart
│       │   │   └── logging.md
│       │   └── config/         # Module directory
│       │       ├── settings.dart
│       │       └── config.md
│       └── client/             # Part directory
│           ├── client.md       # Part documentation
│           ├── http/           # Module directory
│           │   ├── client.dart
│           │   └── http.md
│           └── storage/        # Module directory
│               ├── cache.dart
│               └── storage.md
├── example/                    # Examples directory
│   ├── core/
│   │   ├── logging/
│   │   └── config/
│   └── client/
│       ├── http/
│       └── storage/
├── test/                       # Tests directory
│   ├── core/
│   │   ├── logging_test.dart
│   │   └── config_test.dart
│   └── client/
│       ├── http_test.dart
│       └── storage_test.dart
├── doc/                        # Documentation directory
│   ├── architecture.md
│   └── coding_guidelines.md
├── pubspec.yaml
├── README.md
└── CHANGELOG.md

Multi-Project Workspace Example

my_workspace/                   # Workspace root
├── README.md                   # Workspace documentation
├── core_package/               # Project directory
│   ├── lib/
│   │   └── src/
│   │       ├── utils/          # Module directory
│   │       └── models/         # Module directory
│   ├── test/
│   ├── pubspec.yaml
│   └── README.md               # Project documentation
├── client_app/                 # Project directory
│   ├── lib/
│   │   ├── features/           # Part directory (feature-based)
│   │   │   ├── auth/           # Module directory
│   │   │   └── home/           # Module directory
│   │   └── shared/             # Part directory
│   │       └── widgets/        # Module directory
│   ├── assets/                 # Assets directory
│   ├── test/
│   ├── android/
│   ├── ios/
│   ├── pubspec.yaml
│   └── README.md               # Project documentation
├── server_app/                 # Project directory
│   ├── bin/
│   │   └── server.dart
│   ├── lib/
│   │   └── src/
│   │       ├── api/            # Module directory
│   │       └── services/       # Module directory
│   ├── assets/                 # Assets directory
│   ├── test/
│   ├── pubspec.yaml
│   └── README.md               # Project documentation
└── shared_package/             # Project directory
    ├── lib/
    │   └── src/
    │       ├── models/          # Module directory
    │       └── constants/       # Module directory
    ├── test/
    ├── pubspec.yaml
    └── README.md               # Project documentation

Flutter Application (Single-Project Workspace)

my_app/                         # Workspace root = Project root
├── lib/                        # Source directory
│   ├── main.dart               # Entry point
│   ├── features/               # Part directory (feature-based modules)
│   │   ├── auth/               # Module directory
│   │   │   ├── login_screen.dart
│   │   │   └── auth_service.dart
│   │   ├── home/               # Module directory
│   │   │   └── home_screen.dart
│   │   └── profile/            # Module directory
│   │       └── profile_screen.dart
│   ├── shared/                 # Part directory
│   │   ├── widgets/            # Module directory
│   │   └── utils/              # Module directory
│   └── config/                 # Module directory (single-module part)
│       └── app_config.dart
├── assets/                     # Assets directory
│   ├── images/
│   ├── fonts/
│   └── config/
│       └── settings.json
├── test/                       # Tests directory
│   └── features/
│       └── auth/
│           └── auth_service_test.dart
├── android/
├── ios/
├── pubspec.yaml
├── README.md
└── CHANGELOG.md

Dart Server (Single-Project Workspace)

my_server/                      # Workspace root = Project root
├── bin/                        # Entry points directory
│   └── server.dart
├── lib/
│   └── src/                    # Source directory
│       ├── api/                # Module directory
│       │   ├── routes.dart
│       │   ├── handlers.dart
│       │   └── api.md
│       ├── services/           # Module directory
│       │   ├── user_service.dart
│       │   ├── auth_service.dart
│       │   └── services.md
│       └── database/           # Module directory
│           ├── connection.dart
│           ├── repositories.dart
│           └── database.md
├── assets/                     # Assets directory
│   ├── config/
│   │   └── server_config.yaml
│   └── static/
│       └── index.html
├── test/                       # Tests directory
│   ├── api_test.dart
│   └── services_test.dart
├── doc/                        # Documentation directory
│   └── deployment.md
├── Dockerfile
├── docker-compose.yaml
├── pubspec.yaml
└── README.md

Implementation Notes

Metadata Generation Process

1. Workspace Detection: Check for single or multi-project workspace 2. Project Detection: Analyze each pubspec.yaml to determine project type 3. Source Location: Identify source directory based on project type 4. Part Analysis: Determine if project has parts or flat module structure 5. Module Discovery: Scan for modules in appropriate locations 6. Documentation Mapping: Locate all documentation files (workspace, project, part, module) 7. Asset Mapping: Catalog assets and resources 8. Relationship Mapping: Identify dependencies between modules 9. Validation: Check for required files and structural integrity

Path Conventions

All paths in metadata should follow these conventions:

  • Absolute Paths: Use root_path fields for workspace/project roots
  • Relative Paths: All other paths are relative to their container
  • Project path relative to workspace root
  • Part path relative to project root
  • Module path relative to project root
  • Directory Paths: Paths ending with content (not extensions) are directories
  • lib/src/core - directory
  • assets - directory
  • example/authentication - directory
  • File Paths: Paths with extensions are files
  • README.md - file
  • authentication.md - file
  • pubspec.yaml - file

Handling Edge Cases

  • Mixed Structures: Some projects mix conventions (e.g., lib/src/ + lib/features/)
  • Solution: Support multiple source paths, prioritize by convention
  • Monorepos: Multiple packages in single repository
  • Solution: Treat each pubspec.yaml as separate project
  • Generated Code: Extensive use of code generation
  • Solution: Track source files (.dart), exclude generated (.g.dart)
  • Legacy Projects: Non-standard structures
  • Solution: Provide override configuration for custom structures