Project Structure

This document explains the organization and architecture of the WordZero codebase, helping developers understand the project layout and contribute effectively.

📁 Directory Structure

wordZero/
├── pkg/                     # Core library packages
│   ├── document/           # Document manipulation core
│   ├── style/              # Style system
│   └── markdown/           # Markdown conversion utilities
├── examples/               # Example applications and demos
│   ├── basic/             # Basic usage examples
│   ├── advanced_features/ # Advanced feature demonstrations
│   ├── table/             # Table manipulation examples
│   ├── style_demo/        # Style system showcase
│   ├── formatting/        # Text formatting examples
│   ├── template_demo/     # Template system usage
│   ├── markdown_demo/     # Markdown conversion examples
│   └── page_settings/     # Page configuration examples
├── test/                   # Test files and test data
│   ├── output/            # Test output files
│   └── fixtures/          # Test fixtures and sample data
├── benchmark/              # Performance benchmarks
│   ├── golang/            # Go benchmarks
│   ├── javascript/        # JavaScript comparison benchmarks
│   ├── python/            # Python comparison benchmarks
│   └── results/           # Benchmark results and charts
├── docs/                   # Additional documentation
├── wordZero.wiki/          # Wiki documentation (this documentation)
├── go.mod                  # Go module definition
├── go.sum                  # Go module checksums
├── README.md               # Project overview
├── README_zh.md           # Chinese README
├── CHANGELOG.md           # Version history
├── LICENSE                # Project license
└── debug.go               # Debug utilities

📦 Core Packages

pkg/document

The document package is the core of WordZero, providing the main document manipulation functionality.

Key Files:

• document.go - Main document structure and operations
• paragraph.go - Paragraph handling and text operations
• table.go - Table creation and manipulation
• styles.go - Style application and management
• page.go - Page settings and layout
• properties.go - Document properties and metadata
• advanced.go - Advanced features (TOC, footnotes, etc.)
• iterator.go - Table cell iterator implementation
• format.go - Text formatting structures and methods

Responsibilities:

• Document creation, loading, and saving
• Paragraph and text manipulation
• Table operations and cell management
• Style application and formatting
• Page layout and settings
• Advanced features implementation

pkg/style

The style package defines the style system and predefined styles.

Key Files:

• styles.go - Style definitions and constants
• manager.go - Style management and application
• custom.go - Custom style creation and modification

Responsibilities:

• Predefined style definitions (18 built-in styles)
• Style inheritance and management
• Custom style creation
• Style validation and application

pkg/markdown

The markdown package provides bidirectional conversion between Markdown and Word formats.

Key Files:

• parser.go - Markdown parsing and conversion
• converter.go - Word to Markdown conversion
• formatter.go - Format preservation and mapping

Responsibilities:

• Markdown to Word document conversion
• Word document to Markdown conversion
• Format mapping and preservation
• Content structure translation

🏗️ Architecture Patterns

1. Builder Pattern

WordZero uses the builder pattern for document construction:

// Document builder pattern
doc := document.New()
    .SetTitle("My Document")
    .SetPageSize(document.PageSizeA4)
    .AddParagraph("Content")
    .Save("document.docx")

2. Fluent Interface

Many operations support method chaining for better readability:

para := doc.AddParagraph("Text")
    .SetStyle(style.StyleHeading1)
    .SetAlignment(document.AlignmentCenter)

3. Iterator Pattern

Table operations use iterators for efficient cell traversal:

iterator := table.GetCellIterator()
for iterator.HasNext() {
    cell := iterator.Next()
    // Process cell
}

4. Factory Pattern

Document and component creation uses factory methods:

doc := document.New()              // Document factory
table := doc.AddTable(3, 3)       // Table factory
para := doc.AddParagraph("text")   // Paragraph factory

🧪 Testing Structure

Test Organization

test/
├── unit/                   # Unit tests
│   ├── document_test.go   # Document operations tests
│   ├── table_test.go      # Table functionality tests
│   ├── style_test.go      # Style system tests
│   └── format_test.go     # Formatting tests
├── integration/           # Integration tests
│   ├── complete_test.go   # End-to-end workflows
│   └── performance_test.go # Performance tests
├── fixtures/              # Test data and samples
│   ├── sample.docx       # Sample Word documents
│   ├── test_data.json    # Test data sets
│   └── expected/         # Expected output files
└── output/               # Test output directory

Testing Conventions

1. File Naming: Tests follow *_test.go convention
2. Function Naming: Test functions start with Test
3. Benchmark Naming: Benchmark functions start with Benchmark
4. Test Data: Stored in fixtures/ directory
5. Output Isolation: Each test uses unique output files

📊 Examples Structure

Example Categories

The examples are organized by complexity and feature focus:

Basic Examples (examples/basic/)

• Simple document creation
• Basic text and paragraph operations
• Fundamental style application

Advanced Examples (examples/advanced_features/)

• Complex document structures
• Advanced features usage
• Multiple feature integration

Specialized Examples

• table/ - Table operations and styling
• style_demo/ - Style system showcase
• formatting/ - Text formatting options
• template_demo/ - Template-based generation
• markdown_demo/ - Format conversion
• page_settings/ - Page configuration

Example Conventions

1. Self-contained: Each example is a complete, runnable program
2. Output Directory: All examples save to examples/output/
3. Error Handling: Comprehensive error checking and logging
4. Documentation: Inline comments explaining key concepts
5. Progressive Complexity: Examples build on previous concepts

🚀 Development Workflow

Adding New Features

1. Package Selection: Determine the appropriate package
2. Interface Design: Design public APIs first
3. Implementation: Implement core functionality
4. Testing: Write comprehensive tests
5. Examples: Create usage examples
6. Documentation: Update relevant documentation

Code Organization Principles

1. Single Responsibility: Each package has a clear, focused purpose
2. Minimal Dependencies: Avoid unnecessary external dependencies
3. Consistent APIs: Follow established patterns across packages
4. Error Handling: Use standard Go error handling patterns
5. Documentation: Comprehensive godoc comments

📝 Documentation Structure

Wiki Organization

The documentation is organized in a logical learning progression:

1. Getting Started (01-05): Basic concepts and operations
2. Core Features (06-08): Main functionality areas
3. Advanced Topics (09-12): Complex features and best practices
4. Reference (13-16): Detailed specifications and analysis

Documentation Types

• Tutorials: Step-by-step learning guides
• How-to Guides: Problem-solving focused
• Reference: Comprehensive API documentation
• Explanation: Conceptual background and design decisions

🔧 Build and Development

Prerequisites

• Go 1.19 or higher
• Git for version control
• Make (optional, for build automation)

Development Commands

# Run tests
go test ./...

# Run specific package tests
go test ./pkg/document

# Run benchmarks
go test -bench=. ./...

# Generate documentation
go doc -all ./pkg/document

# Build examples
go build ./examples/basic

# Run linting (if configured)
golangci-lint run

Code Quality

1. Formatting: Use gofmt for consistent formatting
2. Linting: Follow golangci-lint recommendations
3. Testing: Maintain >80% test coverage
4. Documentation: Write comprehensive godoc comments
5. Performance: Regular benchmark testing

🎯 Contributing Guidelines

Code Contributions

1. Fork and Branch: Create feature branches from main
2. Tests Required: All new code must include tests
3. Documentation: Update relevant documentation
4. Examples: Provide usage examples for new features
5. Backwards Compatibility: Maintain API compatibility

Documentation Contributions

1. Accuracy: Ensure technical accuracy
2. Clarity: Write clear, beginner-friendly explanations
3. Examples: Include practical code examples
4. Completeness: Cover all aspects of features
5. Maintenance: Keep documentation current with code changes

📋 Module Dependencies

Direct Dependencies

• Standard Library Only: WordZero uses only Go standard library
• No External Dependencies: Minimizes dependency management issues
• Self-contained: Complete functionality without external packages

Internal Dependencies

pkg/document ← pkg/style     # Document uses style definitions
pkg/document ← pkg/markdown  # Markdown conversion uses document
examples/* ← pkg/*           # Examples use all packages

🔍 File Conventions

Naming Conventions

• Files: snake_case.go
• Packages: lowercase
• Types: PascalCase
• Functions: PascalCase (exported), camelCase (unexported)
• Constants: PascalCase or UPPER_CASE
• Variables: camelCase

File Organization

• Main functionality: package_name.go
• Types and structures: types.go
• Constants and enums: constants.go
• Utilities: utils.go
• Tests: *_test.go

---

This structure provides a solid foundation for understanding, using, and contributing to the WordZero project. The modular design ensures maintainability while the comprehensive examples and documentation support both learning and production use.