GitHub - julianscunha/Tech.Forge: Plataforma corporativa modular para execução de ferramentas técnicas e comerciais via plugins

A modular platform engine for technical & business tools.

Build once as a module — install, run and document it inside a single lightweight desktop platform.

✨ O que é o TechForge?

TechForge é uma plataforma core modular, local-first e otimizada para desktop, feita para hospedar ferramentas técnicas e comerciais como módulos plugáveis: sizing de backup, health checks de virtualização, análise de leads, integrações cloud — qualquer ferramenta interna pode se tornar um módulo.

O Core é pequeno e estável. Toda funcionalidade de negócio vive em módulos com ciclo de vida completo:

descoberta → validação → registro → instalação → execução → documentação → remoção

Por que não uma app monolítica? Por que módulos?

Pensa na sua rotina hoje: uma aba pro monitoramento, outra pro cofre de senhas, outra pro acesso remoto aos servidores, mais uma pro dashboard de backup, outra pro chamado aberto — cada sistema com login próprio, visual próprio, e zero contexto entre eles. Trocar de ferramenta é trocar de aba, de senha, de mental model.

No TechForge isso tudo é módulo dentro da mesma plataforma: mesma navegação, mesmo login, mesma tela. Monitoramento, cofre de senhas e acesso remoto convivendo lado a lado, sem abrir dez sistemas pra fazer uma tarefa. Você instala só o que precisa, organiza do seu jeito — e quando aparece uma ferramenta nova, interna ou de terceiros, ela entra como mais um módulo, não mais um sistema pra gerenciar.

Monólito tradicional	TechForge
Cada ferramenta é um projeto separado	Todas as ferramentas em uma única plataforma
UI, auth, config e logs duplicados a cada app	Infraestrutura compartilhada: shell, navegação, package manager, docs
Deploy e atualização manuais por ferramenta	`.mod` empacotado, instalado e atualizado com rollback
Conhecimento espalhado	Documentation Engine indexa tudo, com busca e contexto p/ IA
Cada equipe reinventa login, tema e navegação	Personalize do seu jeito — módulos que você instala, na ordem que faz sentido pra você

Pensa nisso como o VS Code das ferramentas internas da sua empresa: um core enxuto que não faz nada de negócio sozinho, e uma extensão pra cada coisa que você precisa — sem esperar um roadmap de terceiro pra ter a ferramenta que falta, você mesmo cria o módulo.

Este repositório é só a plataforma — os módulos ficam à parte

Este repositório (Tech.Forge) contém só o Core: o motor que carrega, executa e gerencia módulos. Ele não vem com módulos de negócio prontos (fora dois exemplos de referência usados internamente para testes).

Os módulos reais — as ferramentas que você de fato usa dentro da plataforma — vivem num catálogo separado: Tech.Forge.Modules. Se você quer ver o que já existe pra instalar, ou criar um módulo novo, é lá que você deve ir depois de ter o Core rodando.

🏗️ Arquitetura

Diagrama (Desktop, Core Backend, Core Frontend)

flowchart LR
    subgraph Desktop
        L[🚀 Launcher] --> B
        L --> F
        CLI[⌨️ CLI techforge] --> L
    end
    subgraph Core Backend [Core Backend — FastAPI :8000]
        B[API /api/v1] --> PM[Package Manager]
        B --> ME[Module Engine]
        B --> RT[Runtime]
        B --> DE[Doc Engine]
        PM --> DB[(SQLite async)]
        ME --> DB
        ME --> MODS[modules/installed/*.mod]
    end
    subgraph Core Frontend [Core Frontend — React :5173]
        F[App Shell] --> NAV[Navegação dinâmica]
        F --> MH[Module Host]
        F --> MKT[Marketplace UI]
        F --> DC[Developer Center]
    end
    B <--> F

O fluxo de um módulo

Diagrama (create → validate → package → install → runtime)

flowchart TD
    A["techforge create-module"] --> B["Desenvolve backend + frontend + docs"]
    B --> C["techforge validate-module<br/>mesma lógica do validator do Core"]
    C --> D["techforge package-module<br/>ZIP .mod + manifest + checksum SHA-256"]
    D --> E["Install (API ou import na UI)<br/>valida manifest → compatibilidade → extração atômica"]
    E --> F{Válido e compatível?}
    F -- Não --> G["Rollback — nenhum arquivo residual<br/>erro registrado no operation log"]
    F -- Sim --> H["Registrado no Registry + DB"]
    H --> I["NavigationBuilder injeta item no menu<br/>por categoria/vendor/metadados"]
    I --> J["Plugin Loader monta entry_backend<br/>ModuleHost serve o frontend do módulo no App Shell"]
    J --> K["Doc Engine indexa docs do módulo<br/>completeness check + busca global"]
    K --> L["Update com backup · Remove com cleanup"]

📦 Estrutura do Projeto

TechForge/
├── core/
│   ├── backend/app/
│   │   ├── api/routes/        # Rotas FastAPI (/api/v1/*)
│   │   ├── module_engine/     # manifest · validator · registry · loader · plugin_loader
│   │   ├── package_manager/   # install/remove/update/import · compatibilidade · log
│   │   ├── doc_engine/        # indexação · busca · contratos API · completeness
│   │   ├── runtime/           # estado da plataforma (status/eventos)
│   │   ├── models/ schemas/   # SQLAlchemy + pydantic
│   │   └── core/              # settings centralizado (env vars)
│   └── frontend/src/
│       ├── pages/             # Dashboard · Modules · Marketplace · Developer Center
│       ├── components/        # AppShell · Sidebar · ModuleHost · LoaderJournal
│       └── store/             # zustand (nav, tema, sidebar)
├── modules/
│   ├── repository/            # Catálogo local de pacotes .mod
│   ├── installed/             # Módulos instalados (hello_world de exemplo)
│   └── cache/                 # Cache de downloads
├── launcher/                  # Splash · single-instance · health-readiness · shutdown ordenado
├── cli/techforge_cli/         # create/validate/package-module · start/stop/status
├── sdk/python/                # SDK para desenvolvedores de módulos
├── docs/                      # INDEX.md · architecture/ · adr/ · developer-center/ · limitations.md · roadmap.md
├── config/                    # .env
└── tests/ → core/backend/tests/  # 959 testes pytest (unit/integration/contract/e2e/smoke)

🚀 Quick Start

Pré-requisitos

Python 3.11+
Node.js 18+

Um comando (via launcher)

pip install -e cli
techforge start     # sobe backend + frontend + abre o browser
techforge status    # verifica saúde
techforge stop      # shutdown ordenado
techforge update    # git pull + deps + build + migrations, só em clone git

O launcher garante instância única (pidfile), espera o backend ficar pronto por health check (não por sleep), loga tudo em logs/ e só mata PIDs que ele mesmo criou.

Manual

Backend

cd core/backend
python -m venv .venv && .venv/Scripts/pip install -r requirements.txt
python run.py
# API      → http://127.0.0.1:8000
# Swagger  → http://127.0.0.1:8000/api/docs
# Health   → GET /api/v1/platform/health  {status, platform, version}

⚠️ Rode sempre a partir de core/backend/ — o caminho do SQLite é relativo ao CWD.

Frontend

cd core/frontend
npm install
npm run dev          # http://localhost:5173
npm run build        # tsc -b && vite build
npm run lint         # zero-warnings policy

Configuração (.env)

Todas as variáveis em um único lugar (config/.env, ver config/.env.example). Nada de URLs/portas/caminhos hardcoded no código.

PLATFORM_NAME=TechForge
PLATFORM_VERSION=1.0.0
HOST=127.0.0.1
PORT=8000
DATABASE_URL=sqlite+aiosqlite:///.../config/techforge.db
CORS_ORIGINS=["http://localhost:5173"]

Trocar DATABASE_URL prepara migração futura para PostgreSQL — dependências específicas de SQLite ficam isoladas na camada de dados.

🧪 Testes

959 testes no backend (core/backend/tests/), organizados por nível via pytest markers (unit/integration/contract/e2e/smoke/regression, --strict-markers); 133 no CLI (cli/tests/). CI roda tudo automaticamente em cada push/PR (.github/workflows/ci.yml).

Duas falhas conhecidas dependem de ordem de execução da suíte completa (passam isoladamente) — não são regressão, ver docs/limitations.md.

cd core/backend
python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt

.venv/Scripts/python.exe -m pytest tests -q            # suíte completa
.venv/Scripts/python.exe -m pytest tests -m unit -q    # só um nível
.venv/Scripts/python.exe -m ruff check ../../core/backend/app ../../cli ../../sdk  # static checks

cd core/frontend
npm run lint     # eslint, zero-warnings policy
npm run build    # tsc -b && vite build

cd cli
python -m pytest tests -q

Release Readiness — gate agregado antes de uma release

techforge release-check                             # 5 checks vivos + pytest + npm build
techforge release-check --skip-tests --skip-build    # só os checks vivos (mais rápido)
techforge modules quality <id>                       # relatório de qualidade de um módulo

Sai com código != 0 (Release: BLOCKED) se qualquer checagem falhar.

🧩 Criando seu primeiro módulo

Todo módulo é um pacote .mod (ZIP) com um manifest.yaml declarativo — ver a referência completa dos campos:

id: hello_world
name: Hello World
version: 1.0.0
platform_min_version: "1.0.0"

module_type: service          # application | service
category: examples
vendor: TechForge
author: TechForge Team
description: Módulo de referência.

icon: blocks                          # obrigatório — nome lucide-react kebab-case
order: 10                             # obrigatório — posição na sidebar

entry_backend: backend/main.py        # router FastAPI montado pelo Plugin Loader
entry_frontend: frontend/index.js     # ESM compilado — carregado no Module Host

techforge create-module meu_modulo      # scaffold completo
techforge validate-module ./meu_modulo  # mesma lógica do Core validator
techforge package-module ./meu_modulo   # gera meu_modulo.mod (ZIP assinável)
# Instale pela UI: Marketplace → Import .mod

O módulo aparece automaticamente na navegação, seus endpoints são montados sob /api/v1 e sua documentação entra no índice com score de completude.

🔌 API Reference

Platform & Runtime

Method	Path	Descrição
GET	`/api/v1/platform/health`	Health check da spec (status/platform/version/db)
GET	`/api/v1/platform/status`	Status + contadores (dashboard)
GET	`/api/v1/runtime/status`	Estado runtime (bootstrapping/ready/shutting_down)
GET	`/api/v1/health`	Saúde por módulo registrado

Modules & Registry

Method	Path	Descrição
GET	`/api/v1/modules`	Lista módulos instalados
POST	`/api/v1/modules`	Registra módulo
GET	`/api/v1/modules/:id`	Detalhe do módulo
GET	`/api/v1/registry/navigation`	Árvore de navegação por metadados
GET	`/api/v1/categories` · POST · GET/:slug	Categorias

Marketplace / Package Manager

Method	Path	Descrição
GET	`/api/v1/marketplace/installed·available·updates`	Catálogo local
POST	`/api/v1/marketplace/install/:module_id`	Instalação validada com rollback
DELETE	`/api/v1/marketplace/remove/:module_id`	Remoção física + cleanup
POST	`/api/v1/marketplace/update/:module_id`	Atualização com backup
POST	`/api/v1/marketplace/import`	Importar .mod por upload
POST	`/api/v1/marketplace/compatibility`	Verificação de compatibilidade
GET	`/api/v1/marketplace/log`	Operation log
POST	`/api/v1/marketplace/install-remote/:module_id`	Instalação remota assíncrona (retorna job)
GET	`/api/v1/marketplace/install-jobs/:job_id`	Polling de progresso da instalação remota

Catálogo de Módulos (multi-fonte)

Method	Path	Descrição
GET	`/api/v1/catalog/modules`	Lista módulos de todas as fontes (local + oficial + custom), com filtros/paginação
GET	`/api/v1/catalog/modules/:module_id`	Detalhe de um módulo do catálogo
GET	`/api/v1/catalog/categories`	Categorias com contagem
GET	`/api/v1/catalog/updates`	Módulos instalados com atualização disponível
GET/POST	`/api/v1/catalog/sources`	Lista/adiciona fontes customizadas
DELETE	`/api/v1/catalog/sources/:id`	Remove fonte customizada
GET/POST/DELETE	`/api/v1/catalog/favorites`	Favoritos locais (sem avaliação pública)

Configuration & Persistence

Method	Path	Descrição
GET	`/api/v1/system/storage/status`	Saúde do storage (leitura + escrita)
GET	`/api/v1/system/migrations/status`	Head vs. revisão atual do Alembic
GET	`/api/v1/config`	Configuração de plataforma efetiva (também serve de export)
GET/PUT	`/api/v1/modules/:module_id/config`	Configuração de módulo (schema do manifest, validada)
POST	`/api/v1/modules/:module_id/config/validate`	Valida sem persistir

Quality & Release Engineering

Method	Path	Descrição
GET	`/api/v1/system/version`	Versão da plataforma (fonte única: `PLATFORM_VERSION`)
GET	`/api/v1/release/readiness`	Release Readiness Report (versão, changelog, docs, migrations, storage)
GET	`/api/v1/modules/:module_id/quality`	Module Quality Report (status, docs, compatibilidade, contrato)
GET	`/api/v1/modules/:module_id/release-readiness`	Mesmo dado do quality, framing de gate

CLI: techforge version · techforge release-check [--skip-tests] [--skip-build] · techforge modules quality <id> · techforge modules release-check <id>.

Observability & Diagnostics

Method	Path	Descrição
GET	`/api/v1/diagnostics`	Snapshot completo (platform/storage/runtime/módulos)
GET	`/api/v1/diagnostics/errors?limit=`	Erros recentes (Error Registry, com código de diagnóstico)
GET	`/api/v1/diagnostics/executions?limit=`	Execuções recentes (module_id, status, duração)
GET	`/api/v1/diagnostics/resources`	Uso de recursos (CPU/memória/disco)
GET	`/api/v1/diagnostics/heaviest-modules?limit=`	Módulos por espaço em disco + duração + taxa de falha
GET	`/api/v1/diagnostics/export?format=json\|txt`	Export de relatório de diagnóstico
GET	`/api/v1/diagnostics/support-bundle`	Support Bundle sanitizado (ZIP)
GET	`/api/v1/modules/:id/diagnostics` · `/executions`	Diagnóstico e histórico de execução por módulo

CLI: techforge diagnostics · techforge modules diagnostics <id> · techforge logs --follow.

Notifications

Method	Path	Descrição
GET	`/api/v1/notifications?unread_only=&limit=`	Lista notificações (mais recentes primeiro)
POST	`/api/v1/notifications`	Cria `{level: info\|warning\|error\|success, title, message?}`
GET	`/api/v1/notifications/unread-count`	Contador de não lidas (badge do bell)
POST	`/api/v1/notifications/:id/read` · `/read-all`	Marcar como lida

Documentation Engine

Method	Path	Descrição
GET	`/api/v1/docs/summary` · `/list` · `/article/:path`	Documentação indexada
GET	`/api/v1/docs/search?q=`	Busca com ranking
GET	`/api/v1/docs/contracts[/:module_id]`	Contratos de serviço tipados (API yaml)
GET	`/api/v1/docs/completeness[/:module_id]`	Compliance de docs por módulo
GET	`/api/v1/docs/export/ai-context`	Exporta contexto para LLMs
POST	`/api/v1/docs/reindex`	Reconstrói o índice

🗺️ Roadmap

Ver docs/roadmap.md para o que já está pronto e o que depende de decisões de produto ainda em aberto (multiusuário/servidor central, ecossistema público de módulos). Limitações conhecidas e decisões conscientes de escopo estão em docs/limitations.md.

🤝 Contribuindo

A comunidade mantém o ecossistema através de módulos — o Core permanece pequeno de propósito.

Fork → branch → techforge create-module
Siga o guia: docs/developer-center/guides/development-guide.md
Valide docs: GET /api/v1/docs/completeness/<seu-modulo> deve passar
Rode os testes antes do PR:

cd core/backend && .venv/Scripts/python.exe -m pytest tests -q
cd core/frontend && npm run lint && npm run build

Guia completo (setup local, Core vs. módulo, padrão de commit) em CONTRIBUTING.md. Encontrou uma vulnerabilidade? Veja SECURITY.md em vez de abrir uma issue pública.

📖 Documentação

Doc	Conteúdo
`docs/INDEX.md`	Índice categorizado de toda a documentação
`docs/architecture.md`	Arquitetura do Core
`docs/architecture/`	Inventário de componentes, contratos públicos, mapa de dependências
`docs/adr/`	Decisões de arquitetura registradas (ADRs)
`docs/limitations.md`	Limitações conhecidas e decisões conscientes de escopo
`docs/roadmap.md`	O que vem a seguir
`docs/developer-center/guides/core-development-setup.md`	Setup do Core
`docs/developer-center/`	Guias, referência do manifest, exemplos

_{TechForge — Local first. Modular by design. Lean by principle.}

Name		Name	Last commit message	Last commit date
.github		.github
cli		cli
config		config
core		core
docs		docs
launcher/techforge_launcher		launcher/techforge_launcher
modules/installed/hello_world		modules/installed/hello_world
scripts		scripts
sdk		sdk
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Navigation Menu

Uh oh!

Repository files navigation

✨ O que é o TechForge?

Por que não uma app monolítica? Por que módulos?

Este repositório é só a plataforma — os módulos ficam à parte

🏗️ Arquitetura

O fluxo de um módulo

📦 Estrutura do Projeto

🚀 Quick Start

Pré-requisitos

Um comando (via launcher)

Manual

🧪 Testes

🧩 Criando seu primeiro módulo

🔌 API Reference

🗺️ Roadmap

🤝 Contribuindo

📖 Documentação

About

Releases

Sponsor this project

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

✨ O que é o TechForge?

Por que não uma app monolítica? Por que módulos?

Este repositório é só a plataforma — os módulos ficam à parte

🏗️ Arquitetura

O fluxo de um módulo

📦 Estrutura do Projeto

🚀 Quick Start

Pré-requisitos

Um comando (via launcher)

Manual

🧪 Testes

🧩 Criando seu primeiro módulo

🔌 API Reference

🗺️ Roadmap

🤝 Contribuindo

📖 Documentação

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Used by

Contributors

Languages