# Junior Developer Quickstart

## 1. Overview

This guide explains how to set up the development environment, run the application, and make your first contribution.

## 2. Prerequisites

- **Node.js** (v18 or later)
- **pnpm** (package manager)
- **Docker** (for backend services, optional)
- **Git** (version control)

## 3. Repository Setup

```bash
# Clone the repository
git clone https://github.com/your-org/zui.git
cd zui

# Install dependencies
pnpm install
```

## 4. Running the Application

### Frontend

```bash
pnpm dev
```

Open <http://localhost:3000> to see the app.

### Backend

```bash
pnpm start
```

The backend API will be available at <http://localhost:5000>.

## 5. Making Your First Contribution

1. **Create a feature branch**:

   ```bash
   git checkout -b feat/your-first-contribution
   ```

2. **Make a small change**:
   - Improve a README typo.
   - Add a missing JSDoc comment.
   - Fix a minor bug.
3. **Run the appropriate tests** to ensure your change doesn't break anything:

   ```bash
   pnpm test
   ```

4. **Commit your changes** with a clear message:

   ```bash
   git commit -am "feat: brief description of change"
   ```

5. **Push the branch** to GitHub:

   ```bash
   git push origin feat/your-first-contribution
   ```

6. **Open a Pull Request** on GitHub, linking the relevant issue.

## 6. Coding Standards

- Follow the patterns in **ARCHITECTURE.md** and **CONTRIBUTING.md**.
- Use TypeScript with strict mode.
- Add JSDoc for all public APIs.
- Keep changes small and focused.

## 7. Helpful Links

- **ARCHITECTURE.md** - High-level architecture overview.
- **PERFORMANCE_IMPROVEMENTS.md** - Performance improvement plan.
- **CODE_REVIEW_CHECKLIST.md** - Checklist for reviewers.

## 8. FAQ

**Q:** Do I need to write tests?  
**A:** For bug fixes and new features, yes. Unit tests and integration tests are located under `frontend/src/app/**/*.test.tsx`.

**Q:** How do I run the linter?  
**A:** `pnpm lint`.

**Q:** Where can I find more documentation?  
**A:** See the `docs/` directory and the repository wiki.

---\n*Happy coding!*