# Documentation Index

**Network Scanner & Visualization Tool**  
**Version**: 1.0.0 | **Last Updated**: December 4, 2025

Welcome to the comprehensive documentation for the Network Scanner Tool. This index will guide you to the right documentation for your needs.

---

## 🚀 Start Here

**New to the project?** Follow this path:

1. **[README.md](../README.md)** - Project overview, features, and quick setup
2. **[QUICKSTART.md](../QUICKSTART.md)** - Get running in 5 minutes
3. **[docs/setup/docker.md](setup/docker.md)** - Docker deployment guide
4. **[docs/project-status.md](project-status.md)** - Current status and feature completeness

**Experienced developer?** Jump to:
- **[.github/copilot-instructions.md](../.github/copilot-instructions.md)** - Critical patterns and gotchas for AI agents
- **[docs/development/contributing.md](development/contributing.md)** - Development workflow

---

## 📚 Documentation Structure

### Architecture & Design

Understanding the system design and architecture decisions.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [overview.md](architecture/overview.md) | Complete architecture design, technology stack justification | Before making structural changes |
| [fullstack.md](architecture/fullstack.md) | Full-stack implementation overview | Understanding data flow |
| [project-status.md](project-status.md) | Current feature completeness, known issues | Checking what's implemented |

### Setup & Deployment

Getting the application running in different environments.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [docker.md](setup/docker.md) | Docker & Docker Compose setup | Containerized deployment |
| [local-development.md](setup/local-development.md) | Local development setup without Docker | Development environment |
| [production.md](setup/production.md) | Production deployment (cloud, Kubernetes) | **TODO** - Production release |

### API Reference

Details on REST endpoints, WebSocket, and data contracts.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [endpoints.md](api/endpoints.md) | REST API endpoint reference | **TODO** - Integrating with API |
| Auto-generated docs | Interactive API documentation | Testing endpoints |
| - http://localhost:8000/docs | OpenAPI/Swagger UI | - |
| - http://localhost:8000/redoc | ReDoc alternative | - |

### Guides

Step-by-step guides for common tasks and workflows.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [scanning-networks.md](guides/scanning-networks.md) | How to scan networks, interpret results | **TODO** - Using the scanner |
| [troubleshooting.md](guides/troubleshooting.md) | Common errors and solutions | Debugging issues |
| [security.md](guides/security.md) | Security best practices, configuration | **TODO** - Hardening for production |

### Development

Resources for contributors and developers.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [contributing.md](development/contributing.md) | Contribution guidelines, PR process | Before submitting changes |
| [testing.md](development/testing.md) | Testing strategy, writing tests | **TODO** - Adding tests |
| [database-schema.md](development/database-schema.md) | Database structure, migrations | **TODO** - Modifying data models |
| Frontend docs | Frontend-specific development | Working on React components |
| - [frontend/README.md](../frontend/README.md) | Frontend overview | - |
| - [frontend/DEVELOPMENT.md](../frontend/DEVELOPMENT.md) | Frontend development guide | - |

### Reference

Quick lookups and command references.

| Document | Purpose | When to Read |
|----------|---------|--------------|
| [quick-reference.md](reference/quick-reference.md) | Command cheat sheet, common tasks | Quick lookups |
| [navigation.md](reference/navigation.md) | Project navigation guide | Finding specific code |

---

## 🔍 Which Document Do I Need?

### "I want to..."

**...get the app running quickly**
→ [QUICKSTART.md](../QUICKSTART.md) + [docs/setup/docker.md](setup/docker.md)

**...understand how it works**
→ [docs/architecture/overview.md](architecture/overview.md) + [README.md](../README.md)

**...fix a bug or error**
→ [docs/guides/troubleshooting.md](guides/troubleshooting.md) + [.github/copilot-instructions.md](../.github/copilot-instructions.md)

**...add a new feature**
→ [docs/development/contributing.md](development/contributing.md) + [.github/copilot-instructions.md](../.github/copilot-instructions.md)

**...deploy to production**
→ [docs/setup/production.md](setup/production.md) *(TODO)* + [docs/guides/security.md](guides/security.md) *(TODO)*

**...understand the API**
→ http://localhost:8000/docs (auto-generated) + [docs/api/endpoints.md](api/endpoints.md) *(TODO)*

**...modify the database**
→ [docs/development/database-schema.md](development/database-schema.md) *(TODO)* + [app/models.py](../app/models.py)

**...work on the frontend**
→ [frontend/DEVELOPMENT.md](../frontend/DEVELOPMENT.md) + [frontend/README.md](../frontend/README.md)

**...check project status**
→ [docs/project-status.md](project-status.md)

---

## 📝 Documentation Guidelines for Contributors

### Before Making Changes

1. **Check existing documentation** - Search this index for relevant docs
2. **Review troubleshooting guide** - Common issues may already be documented
3. **Read copilot instructions** - Critical patterns in [.github/copilot-instructions.md](../.github/copilot-instructions.md)

### When Adding Features

1. **Update API docs** if endpoints change
2. **Update database-schema.md** if models change
3. **Add entry to CHANGELOG.md** (TODO - create this)
4. **Update project-status.md** feature tables

### Documentation Standards

- **Use markdown** for all documentation
- **Include code examples** for patterns and workflows
- **Link between docs** using relative paths
- **Keep up-to-date** - outdated docs are worse than no docs
- **Document "why"** not just "what" - explain design decisions

---

## 🗂️ Archive

Historical documents from development and code reviews:

- [archive/review-2025-12-04/](../archive/review-2025-12-04/) - Code review from December 4, 2025
  - Contains identified issues, critical fixes, and audit reports
  - **All critical issues have been resolved** - see [docs/project-status.md](project-status.md)

---

## 📌 Documentation TODO List

Priority documentation that needs to be created:

### High Priority
- [ ] **docs/setup/production.md** - Cloud deployment, Kubernetes, SSL/TLS setup
- [ ] **docs/guides/troubleshooting.md** - Common errors with solutions
- [ ] **docs/guides/security.md** - Authentication, CORS, rate limiting
- [ ] **docs/development/database-schema.md** - ER diagrams, migrations, relationships

### Medium Priority
- [ ] **docs/api/endpoints.md** - Comprehensive API reference
- [ ] **docs/development/testing.md** - Test strategy, writing tests
- [ ] **CHANGELOG.md** - Version history, breaking changes
- [ ] **docs/guides/scanning-networks.md** - User guide for network scanning

### Low Priority
- [ ] **docs/architecture/decisions/** - ADRs for major design choices
- [ ] **docs/guides/performance.md** - Optimization tips, benchmarks
- [ ] **LICENSE.md** - License information (if applicable)

---

## 🔗 External Resources

- **FastAPI Documentation**: https://fastapi.tiangolo.com/
- **React Flow**: https://reactflow.dev/
- **SQLAlchemy**: https://docs.sqlalchemy.org/
- **Docker**: https://docs.docker.com/
- **TypeScript**: https://www.typescriptlang.org/docs/

---

## 📧 Help & Support

- **For bugs**: Check [docs/guides/troubleshooting.md](guides/troubleshooting.md)
- **For development**: See [docs/development/contributing.md](development/contributing.md)
- **For deployment issues**: Check `docker compose logs backend` or `docker compose logs frontend`
- **For code review**: See archived review at [archive/review-2025-12-04/](../archive/review-2025-12-04/)

---

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