werkzeuge/teamleader_test/CONTRIBUTING.md

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 - Documentation index
• .github/copilot-instructions.md - Critical patterns and gotchas
• docs/guides/troubleshooting.md - Common issues
• docs/project-status.md - Current feature status

2. Check Existing Issues

• Search docs/guides/troubleshooting.md for known issues
• Review 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

# 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)

   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 if feature completeness changes

4. Test thoroughly

   # 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

# 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:

   # ✅ 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:

   # ✅ 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:

   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

// 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

   // 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:

   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 (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 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

# 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
2. Review .github/copilot-instructions.md
3. Search 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)