Professionalize project documentation

Author: albertomateus9

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Mateus P. da Gama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,50 +1,57 @@
 # NetMaster CLI/API
 
-Bem-vindo ao **NetMaster CLI/API**, um projeto open-source concebido como um template base para automação de equipamentos de rede, ideal para uso em Hackathons, desafios de programação e estudos de arquitetura de software.
+Network automation template for provisioning and documenting network devices with a clean, extensible Python architecture.
 
-## Propósito Pedagógico e Técnico
+## Overview
 
-Este repositório foi criado com o objetivo de demonstrar a aplicação de **Clean Architecture** em um projeto Python moderno. Ele separa claramente as responsabilidades, facilitando a escalabilidade, manutenção e testes.
+NetMaster CLI/API is an educational and technical starter project for network automation. It separates domain rules, application use cases, interface adapters, and infrastructure details so students and engineers can evolve the repository into a CLI, REST API, or lab automation tool without mixing business logic with device-specific integrations.
 
-### Arquitetura (Clean Architecture)
+## Problem
 
-A estrutura do projeto está dividida nas seguintes camadas:
+Network teams often start automation scripts as isolated one-off files. That makes testing, reuse, and onboarding difficult. This repository demonstrates a more professional baseline for VLAN provisioning, device inventory, and future SSH/API integrations.
 
-*   **`domain/`**: Contém as Entidades (ex: `NetworkDevice`, `VLAN`) e regras de negócio puras, independentes de frameworks externos.
-*   **`application/`**: Contém os Casos de Uso (ex: `ProvisionVLANUseCase`), orquestrando o fluxo de dados entre as entidades e as interfaces externas.
-*   **`interface_adapters/`**: Responsável por converter os dados no formato mais conveniente para os casos de uso e vice-versa. Aqui residirão as rotas web (FastAPI) e os comandos de terminal (Typer).
-*   **`infrastructure/`**: Camada mais externa, contendo detalhes de implementação técnica, como persistência em banco de dados (SQLAlchemy) e comunicação com os equipamentos de rede via SSH (Netmiko).
+## Architecture
 
-## Stack Tecnológica
+- `domain/`: pure entities such as `NetworkDevice` and `VLAN`.
+- `application/`: use cases such as `ProvisionVLANUseCase`.
+- `interface_adapters/`: future FastAPI routes, Typer commands, and serializers.
+- `infrastructure/`: future persistence, Netmiko drivers, and vendor-specific adapters.
 
-O projeto utiliza as seguintes tecnologias:
+## Stack
 
-*   **Python 3.10+**
-*   [**FastAPI**](https://fastapi.tiangolo.com/): Para criação de uma API RESTful moderna e assíncrona.
-*   [**Uvicorn**](https://www.uvicorn.org/): Servidor ASGI para rodar a aplicação FastAPI.
-*   [**Typer**](https://typer.tiangolo.com/): Para criação de uma Interface de Linha de Comando (CLI) robusta.
-*   [**SQLAlchemy**](https://www.sqlalchemy.org/): ORM para persistência de dados.
-*   [**Netmiko**](https://pynet.twb-tech.com/blog/automation/netmiko.html): Para conexões seguras (SSH) e interação com equipamentos de rede.
+- Python 3.10+
+- FastAPI and Uvicorn for REST APIs
+- Typer for command-line workflows
+- SQLAlchemy for persistence
+- Netmiko for SSH-based network device automation
 
-## Como Iniciar
+## Getting Started
 
-1.  **Clone o repositório:**
-    ```bash
-    git clone <sua-url-do-github>
-    cd netmaster-cli-api
-    ```
+```bash
+git clone https://github.com/albertomateus9/netmaster-cli-api.git
+cd netmaster-cli-api
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
 
-2.  **Ative o ambiente virtual:**
-    *   No Windows: `venv\\Scripts\\activate`
-    *   No Linux/macOS: `source venv/bin/activate`
+On Linux or macOS, activate the environment with:
 
-3.  **Instale as dependências:**
-    ```bash
-    pip install -r requirements.txt
-    ```
+```bash
+source .venv/bin/activate
+```
 
-4.  **Expanda a implementação!**
-    Comece implementando as interfaces em `interface_adapters/` e os adaptadores reais em `infrastructure/` guiados pelos casos de uso em `application/`.
+## Development Direction
 
----
-*Desenvolvido como um template base para aceleração de projetos de engenharia de redes.*
+- Implement repository interfaces for device inventory.
+- Add a Netmiko-backed network service for lab devices.
+- Expose the provisioning use case through FastAPI and Typer.
+- Add tests for domain entities and use-case orchestration.
+
+## Professional Context
+
+This repository reflects practical interests in telecom infrastructure, routing, network automation, and teaching software architecture through realistic engineering scenarios.
+
+## License
+
+MIT. See [LICENSE](LICENSE).