OpenGrammar Project Guide

A comprehensive guide for working with OpenGrammar, an open-source Wails v2 desktop application that provides AI-powered text processing using Claude AI.

Project Architecture

OpenGrammar implements a BYOK (Bring Your Own Key) architecture with comprehensive multilingual support and custom action capabilities.

Technology Stack

Directory Structure

```

/

├── main.go # Application entry point, Wails setup

├── app.go # Core backend logic, Claude API integration

├── go.mod # Go dependencies

├── wails.json # Wails project configuration

└── frontend/

├── src/

│ ├── App.tsx # Main React component

│ └── style.css # Tailwind styles

├── wailsjs/ # Auto-generated TypeScript bindings

├── package.json # Frontend dependencies

└── vite.config.ts # Vite configuration

```

Core Features & Implementation

Backend (`app.go`)

**Primary Method**: `ProcessText(text, apiKey, actionType, language) (string, error)`

**Supported Action Types**:

**Response Structure**: All prompts return structured format:

```

ANALYSIS: [explanation]

FINAL RESULT: [processed text]

```

**API Configuration**:

Frontend (`App.tsx`)

**Key Features**:

Development Workflow

1. Starting Development

```bash

Start Wails dev server (hot reload for frontend + backend)

wails dev

Browser dev server runs on http://localhost:34115

Use browser devtools to debug Go methods

```

2. Frontend-Only Development

```bash

cd frontend

npm install

npm run dev # Vite dev server

npm run build # Build TypeScript + Vite

```

3. Testing Backend Changes

When you modify Go backend methods:

1. Wails automatically regenerates TypeScript bindings in `frontend/wailsjs/`

2. Import updated methods from `frontend/wailsjs/go/main/App`

3. Test in dev mode before building

4. Production Build

```bash

Universal macOS (Intel + Apple Silicon)

wails build -platform darwin/universal -upx

Windows with installer

wails build -platform windows/amd64 -nsis -upx

Linux

wails build -platform linux/amd64 -upx

All platforms

wails build -platform darwin/universal,windows/amd64,linux/amd64 -upx

Production with obfuscation

wails build -platform darwin/universal -obfuscated -trimpath -upx

```

Important Technical Details

Wails-Specific Patterns

1. **Go-to-TypeScript Bindings**: Wails generates TypeScript definitions from Go structs automatically

2. **Method Exposure**: Only capitalized (public) Go methods are exposed to frontend

3. **Frontend Embedding**: Frontend assets embedded in binary via `//go:embed all:frontend/dist`

4. **Binding Setup**: Methods must be bound to App struct in `main.go`

State Management

Response Parsing Logic

1. Split response by `ANALYSIS:` and result section headers

2. Extract text from relevant sections

3. Remove surrounding quotes from final result

4. Fallback to raw response if parsing fails

Error Handling

Known Technical Challenges & Solutions

Tailwind CSS v3 Compatibility

Color Contrast Issues

Quote Removal

Universal Binary Creation

Configuration Files

| File | Purpose |

|------|---------|

| `wails.json` | Wails project settings, build commands, frontend integration |

| `go.mod` | Go dependencies (Wails v2) |

| `frontend/package.json` | React, TypeScript, Vite, Tailwind dependencies |

| `frontend/vite.config.ts` | Vite build configuration |

| `frontend/tailwind.config.js` | Tailwind CSS v3 configuration |

| `frontend/postcss.config.js` | PostCSS configuration for Tailwind |

Development Best Practices

When Modifying Backend (Go)

1. Keep methods public (capitalized) for frontend access

2. Return `(result string, error)` for consistent error handling

3. Test with `wails dev` before building

4. Check generated TypeScript bindings in `frontend/wailsjs/`

When Modifying Frontend (React)

1. Import Go methods from `frontend/wailsjs/go/main/App`

2. Handle errors from Go methods properly

3. Use Tailwind classes for styling (avoid custom CSS)

4. Test bilingual strings for both languages

5. Persist user preferences in LocalStorage

When Adding New Features

1. Add backend method to `app.go`

2. Restart `wails dev` to regenerate bindings

3. Import new method in `App.tsx`

4. Add UI elements with Tailwind styling

5. Update bilingual translations

6. Test error cases

When Building for Distribution

1. Run `npm run build` in `frontend/` first

2. Use appropriate platform flags for target OS

3. Consider `-upx` for compression

4. Test universal builds on both Intel and Apple Silicon

5. Use `-obfuscated -trimpath` for production security

Common Commands Reference

```bash

Development

wails dev # Start dev server

cd frontend && npm run dev # Frontend only

Building

wails build # Current platform

wails build -platform darwin/universal # macOS universal

wails build -platform windows/amd64 # Windows

wails build -platform linux/amd64 # Linux

Go Backend

go mod tidy # Clean dependencies

go build # Build Go app

Frontend

cd frontend

npm install # Install dependencies

npm run build # Build frontend

```

Resources

Project Evolution Timeline

1. **Initial Setup** - Wails v2 calculator template

2. **AI Integration** - Claude API grammar checker

3. **Multilingual** - English/Indonesian support

4. **UI Enhancement** - Tailwind CSS v3 migration

5. **Custom Actions** - Flexible prompt system

6. **Production** - Universal macOS binary + DMG