# SDL3 Parser - Project Structure

```
parser/
├── README.md                      # Project overview and quick start
├── build.zig                      # Build configuration
├── build.zig.zon                  # Dependencies
│
├── src/                           # Source code (900 lines)
│   ├── parser.zig                 # Main entry point, CLI
│   ├── patterns.zig               # Pattern matching & scanning
│   ├── types.zig                  # C to Zig type conversion
│   ├── naming.zig                 # Naming convention handling
│   ├── codegen.zig                # Zig code generation
│   ├── mock_codegen.zig           # C mock generation
│   └── dependency_resolver.zig    # Dependency analysis (NEW)
│
├── test/                          # Test files
│   ├── integration/               # Integration tests
│   │   ├── test_multifield_*.zig
│   │   ├── test_typedef_*.zig
│   │   └── test_flow_*.zig
│   └── (pattern test files)
│
├── docs/                          # Documentation (5,500+ lines)
│   ├── INDEX.md                   # Documentation index
│   │
│   ├── GETTING_STARTED.md         # Installation and first use
│   ├── QUICKSTART.md              # Quick reference
│   ├── API_REFERENCE.md           # Command-line options
│   │
│   ├── ARCHITECTURE.md            # System design
│   ├── DEPENDENCY_RESOLUTION.md   # How deps work
│   ├── KNOWN_ISSUES.md            # Limitations
│   │
│   ├── DEVELOPMENT.md             # Contributing guide
│   ├── ROADMAP.md                 # Future plans
│   │
│   ├── DEPENDENCY_FLOW.md         # Technical deep dive
│   ├── VISUAL_FLOW.md             # Flow diagrams
│   ├── MULTI_FIELD_IMPLEMENTATION.md
│   ├── TYPEDEF_IMPLEMENTATION.md
│   ├── MULTI_HEADER_TEST_RESULTS.md
│   │
│   └── archive/                   # Historical documents
│       └── (planning and status docs)
│
└── zig-out/                       # Build artifacts
    └── bin/sdl-parser             # Executable
```

## Documentation Organization

### User Documentation (Start Here)
1. README.md - Project overview
2. GETTING_STARTED.md - Tutorial
3. QUICKSTART.md - Quick reference
4. API_REFERENCE.md - Complete reference

### Technical Documentation
5. ARCHITECTURE.md - System design
6. DEPENDENCY_RESOLUTION.md - Feature details
7. DEPENDENCY_FLOW.md - Implementation walkthrough
8. VISUAL_FLOW.md - Diagrams

### Development Documentation
9. DEVELOPMENT.md - Contributing guide
10. KNOWN_ISSUES.md - Current limitations
11. ROADMAP.md - Future plans

### Implementation Documentation
12. MULTI_FIELD_IMPLEMENTATION.md - Struct parsing
13. TYPEDEF_IMPLEMENTATION.md - Typedef support
14. MULTI_HEADER_TEST_RESULTS.md - Test results

## Source Code Organization

### Core Pipeline

```
parser.zig (main)
    ↓
patterns.zig (scan)
    ↓
dependency_resolver.zig (resolve)
    ↓
codegen.zig (generate)
    ↓
Output (Zig/C)
```

### Supporting Modules

- `types.zig` - Type conversion utilities
- `naming.zig` - Naming convention utilities
- `mock_codegen.zig` - C mock generation

## Build Outputs

### Local Build

```
zig-out/
├── bin/
│   └── sdl-parser              # Executable
└── (test outputs)
```

### Integration with lib/sdl3

```
lib/sdl3/
├── v2/                          # Generated bindings
│   ├── gpu.zig                  # SDL_gpu.h bindings
│   ├── video.zig                # SDL_video.h (if working)
│   └── ...
└── zig-out/
    ├── gpu_test.zig             # Test bindings
    └── gpu_test_mock.c          # Test mocks
```

## Test Organization

### Unit Tests (in source files)

Each src/*.zig file contains tests at the bottom:
- Pattern matching tests
- Type conversion tests
- Naming convention tests

### Integration Tests (test/integration/)

- `test_multifield_*.zig` - Multi-field struct parsing
- `test_typedef_*.zig` - Typedef scanning
- `test_flow_*.zig` - Dependency resolution
- `test_*.c` - Test input files

### Running Tests

```bash
# All tests
zig build test

# Specific test file
zig test test/integration/test_typedef_simple.zig
```

## Documentation Categories

### For Users
- Getting started, quickstart, API reference
- Focus: How to use the tool

### For Understanding
- Architecture, dependency resolution
- Focus: How it works internally

### For Developers
- Development guide, implementation docs
- Focus: How to extend and contribute

### For Reference
- Technical deep dives, flow diagrams
- Focus: Complete implementation details

## File Size Reference

### Source Code
- Total: ~900 lines production code
- Average: ~150 lines per module
- Largest: dependency_resolver.zig (454 lines)

### Documentation
- Total: ~5,500 lines
- User guides: ~1,500 lines
- Technical docs: ~2,500 lines
- Implementation details: ~1,500 lines

### Tests
- Unit tests: ~400 lines (in source files)
- Integration tests: ~500 lines (separate files)
- Total: ~900 lines

## Quick Navigation

```bash
# Main documentation entry point
cat README.md

# Start tutorial
cat docs/GETTING_STARTED.md

# Command reference
cat docs/API_REFERENCE.md

# Understand internals
cat docs/ARCHITECTURE.md

# Fix issues
cat docs/KNOWN_ISSUES.md

# Contribute
cat docs/DEVELOPMENT.md

# All docs
ls docs/
```

---

**Last Updated**: 2026-01-22  
**Documentation Version**: 2.1  
**Status**: Clean and organized ✅