# Contributing to Network Scanner Tool

Thank you for contributing! This guide will help you understand our development workflow, coding standards, and documentation requirements.

---

## Before You Start

### 1. Read the Documentation

**Required reading before contributing:**

- [docs/index.md](docs/index.md) - Documentation index
- [.github/copilot-instructions.md](.github/copilot-instructions.md) - Critical patterns and gotchas
- [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) - Common issues
- [docs/project-status.md](docs/project-status.md) - Current feature status

### 2. Check Existing Issues

- Search [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) for known issues
- Review [archive/review-2025-12-04/](archive/review-2025-12-04/) for resolved issues
- Check if your feature/fix is already documented

### 3. Understand the Architecture

- Backend: Python 3.11 + FastAPI + SQLAlchemy + SQLite
- Frontend: React 18 + TypeScript + TailwindCSS + React Flow
- Deployment: Docker + Docker Compose + nginx

---

## Development Workflow

### Setting Up Development Environment

```bash
# Clone and navigate to project
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test

# Start with Docker Compose (recommended)
docker compose up -d --build

# Or setup locally (advanced)
# Backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

# Frontend
cd frontend
npm install
npm run dev
```

### Making Changes

1. **Create a branch** (if using git)
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**
   - Follow coding conventions (see below)
   - Write clear commit messages
   - Test your changes locally

3. **Update documentation**
   - **CRITICAL**: Update relevant docs in `docs/`
   - Add entry to CHANGELOG.md (TODO - create this)
   - Update [docs/project-status.md](docs/project-status.md) if feature completeness changes

4. **Test thoroughly**
   ```bash
   # Backend
   docker compose logs backend --tail=50
   curl http://localhost:8000/health
   
   # Frontend
   # Open http://localhost and test UI
   # Check browser console (F12) for errors
   ```

5. **Submit pull request** (if using git workflow)
   - Clear description of changes
   - Reference any related issues
   - Include documentation updates

---

## Coding Standards

### Backend (Python)

**Style Guide**: PEP 8

```python
# Good: Type hints, docstrings, descriptive names
def create_scan(self, config: ScanConfigRequest) -> Scan:
    """
    Create a new scan record.
    
    Args:
        config: Scan configuration
        
    Returns:
        Created scan object
    """
    scan = Scan(
        scan_type=config.scan_type.value,
        network_range=config.network_range,
        status=ScanStatusEnum.PENDING.value
    )
    self.db.add(scan)
    self.db.commit()
    self.db.refresh(scan)
    return scan

# Bad: No types, no docs, unclear names
def cs(c):
    s = Scan(scan_type=c.scan_type.value, network_range=c.network_range)
    self.db.add(s)
    self.db.commit()
    return s
```

**Critical Patterns**:

1. **Database Sessions in Background Tasks**:
   ```python
   # ✅ DO: Create new session
   def scan_wrapper(scan_id: int):
       db = SessionLocal()
       try:
           scan_service.execute_scan(scan_id, db)
       finally:
           db.close()
   
   background_tasks.add_task(scan_wrapper, scan_id)
   
   # ❌ DON'T: Use request session
   background_tasks.add_task(scan_service.execute_scan, scan_id, db)
   ```

2. **Database Constraints**:
   ```python
   # ✅ DO: Commit before adding dependents
   host = self._get_or_create_host(ip)
   self.db.commit()
   self.db.refresh(host)  # Ensure host.id is set
   
   service = Service(host_id=host.id, port=80)
   self.db.add(service)
   
   # ❌ DON'T: Add dependents before commit
   host = self._get_or_create_host(ip)
   service = Service(host_id=host.id, port=80)  # host.id may be None!
   ```

3. **Logging**:
   ```python
   import logging
   logger = logging.getLogger(__name__)
   
   logger.info("Starting scan for 192.168.1.0/24")
   logger.error(f"Scan failed: {error}")
   logger.debug(f"Processing host: {ip}")
   ```

### Frontend (TypeScript/React)

**Style Guide**: TypeScript strict mode, React best practices

```typescript
// Good: Type-safe, clear component structure
interface HostDetailsPanelProps {
  hostId: string;
  onClose: () => void;
}

export default function HostDetailsPanel({ hostId, onClose }: HostDetailsPanelProps) {
  const [host, setHost] = useState<HostWithServices | null>(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    const fetchHost = async () => {
      try {
        setLoading(true);
        const data = await hostApi.getHost(parseInt(hostId));
        setHost(data);
      } catch (err) {
        console.error('Failed to fetch host:', err);
      } finally {
        setLoading(false);
      }
    };
    
    fetchHost();
  }, [hostId]);
  
  return (
    <div className="panel">
      {/* Component JSX */}
    </div>
  );
}

// Bad: No types, unclear structure, no error handling
function Panel(props) {
  const [data, setData] = useState(null);
  
  useEffect(() => {
    fetch('/api/hosts/' + props.id).then(r => r.json()).then(setData);
  }, []);
  
  return <div>{data?.name}</div>;
}
```

**Critical Rules**:

1. **Schema Alignment**: Frontend types MUST match backend schemas exactly
   ```typescript
   // frontend/src/types/api.ts
   export interface Scan {
     network_range: string;  // ← Must match app/schemas.py
   }
   
   // app/schemas.py
   class ScanConfigRequest(BaseModel):
       network_range: str  # ← Must match frontend
   ```

2. **API Error Handling**:
   ```typescript
   try {
     const data = await scanApi.startScan(config);
     // Handle success
   } catch (error) {
     if (axios.isAxiosError(error)) {
       console.error('API Error:', error.response?.data);
     }
     // Handle error
   }
   ```

3. **React Hooks**:
   - Custom hooks in `hooks/` for reusable logic
   - Use `useEffect` dependencies correctly
   - Clean up subscriptions/timers

### Database Changes

**When modifying `app/models.py`:**

1. Update SQLAlchemy model
2. Update Pydantic schema in `app/schemas.py`
3. Update TypeScript types in `frontend/src/types/api.ts`
4. Delete `data/network_scanner.db` (dev) or create migration (prod)
5. Update [docs/development/database-schema.md](docs/development/database-schema.md) (TODO)
6. Restart backend: `docker compose restart backend`

**Reserved Column Names** (avoid these in SQLAlchemy):
- `metadata` - Use `extra_data` instead
- `type` - Use `device_type` or prefix with table name
- Other SQLAlchemy/SQL reserved words

---

## Documentation Requirements

### Mandatory Documentation Updates

**All pull requests MUST include:**

1. **Updated documentation** if API or behavior changes
2. **Entry in CHANGELOG.md** (TODO - create this)
3. **Update to [docs/project-status.md](docs/project-status.md)** if feature status changes
4. **Troubleshooting entry** if fixing a bug

### When to Update Specific Docs

| Change Type | Documentation to Update |
|-------------|-------------------------|
| New API endpoint | `docs/api/endpoints.md` (TODO), add to OpenAPI docs |
| Database schema change | `docs/development/database-schema.md` (TODO) |
| New feature | `docs/project-status.md`, `README.md` |
| Bug fix | `docs/guides/troubleshooting.md` |
| Configuration change | `docs/setup/` files, `.env.example` |
| Architecture decision | `docs/architecture/overview.md` |

### Documentation Style

```markdown
# Good: Clear, actionable, with examples

## Adding a New API Endpoint

1. Create handler in `app/api/endpoints/new_feature.py`:
   ```python
   @router.get("/feature")
   async def get_feature(db: Session = Depends(get_db)):
       return {"data": "value"}
   ```

2. Add to router in `app/api/__init__.py`
3. Update `frontend/src/types/api.ts`

# Bad: Vague, no examples

Add endpoint and update types.
```

---

## Testing Guidelines

### Manual Testing Checklist

Before submitting changes, test:

- [ ] Backend health check: `curl http://localhost/health`
- [ ] Relevant API endpoints work
- [ ] Frontend loads without errors (check F12 console)
- [ ] No TypeScript build errors
- [ ] Docker build succeeds: `docker compose up -d --build`
- [ ] Database operations complete successfully
- [ ] WebSocket updates work (if applicable)
- [ ] No errors in `docker compose logs`

### Automated Testing (TODO)

```python
# Backend tests (when implemented)
pytest tests/

# Frontend tests (when implemented)
cd frontend && npm test
```

---

## Commit Message Guidelines

**Format**: `<type>: <description>`

**Types**:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `refactor:` Code restructuring
- `test:` Adding tests
- `chore:` Maintenance tasks

**Examples**:
```
feat: add host details panel with service information
fix: resolve session management in background tasks
docs: update troubleshooting guide with schema mismatch solution
refactor: simplify topology service to remove layout calculation
```

---

## Code Review Checklist

### For Reviewers

- [ ] Code follows style guidelines
- [ ] Documentation is updated
- [ ] No obvious bugs or security issues
- [ ] TypeScript types match backend schemas
- [ ] Database operations follow critical patterns
- [ ] Logging is appropriate
- [ ] Error handling is present
- [ ] Changes are tested

### For Contributors

Before requesting review:
- [ ] Run through manual testing checklist
- [ ] All documentation requirements met
- [ ] Code is self-documented (clear names, docstrings)
- [ ] Commit messages are clear
- [ ] No debug code or commented-out blocks
- [ ] No hardcoded credentials or secrets

---

## Architecture Decisions

### When to Document an ADR

If you're making a significant architectural decision:
1. Create ADR in `docs/architecture/decisions/` (TODO)
2. Document: Context, Decision, Consequences, Alternatives considered

Examples of ADR-worthy decisions:
- Switching from SQLite to PostgreSQL
- Changing visualization library
- Adding authentication system
- Modifying API versioning strategy

---

## Getting Help

**Before asking:**
1. Check [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md)
2. Review [.github/copilot-instructions.md](.github/copilot-instructions.md)
3. Search [docs/index.md](docs/index.md) for relevant documentation

**For AI agents:**
- ALWAYS check `docs/index.md` before suggesting changes
- ALWAYS verify against `.github/copilot-instructions.md` for critical patterns
- ALWAYS update documentation when making changes

---

## License

(TODO - Add license information)

---

**Last Updated**: December 4, 2025  
**Maintainers**: AI Agents (GitHub Copilot, Claude)