DEV Community: Ênrell

Defining the architecture decisions of Navi

Ênrell — Thu, 26 Feb 2026 08:51:45 +0000

It was 3 AM when I had the idea for Navi a few months ago. I was in bed thinking about the impact of LLMs on developers' hard skills. Before the LLM boom, I improved my coding skills by building projects for my own use. But when OpenAI launched GPT-3, I saw that this technology could be useful. I spent a lot of time playing with GPT-3 code generation, and I remember the feeling I had when I used it to learn OOP. I was like, "What the F*! How the f* do these guys do that?" That was the spark that made my hyperfocus kick in to study the area.

I studied the basics to understand all model architectures, and recently I completed the Information Retrieval and Artificial Intelligence course in college. Now I have solid knowledge to start understanding the present and future of LLMs.

In this article, I will present the architectural decisions behind Navi, and some useful insights about agent strengths and weaknesses based on my humble LLM knowledge.

The difference between agents and agency

Look, I've been deep in the AI space for a while now, and I can tell you one thing: everyone throws around the word "agent" like it's going out of style. But here's the thing — an agent by itself? It's just a fancy function call with commitment issues.

Let me break it down with something real. Imagine you have a single AI model that can answer questions. Cool, right? That's an agent. It's reactive. You ask, it answers. You prompt, it responds. Nothing wrong with that — but it's not exactly... autonomous.

Now, what if that same AI could decide when to search the web, choose to call a database, and opt to save results somewhere? Still an agent. But the moment you connect multiple agents together, give them roles, responsibilities, and a way to communicate?

That's when you have an agency.

The Solo Agent Trap

I've seen this mistake too many times. Developers build a "super agent" that tries to do everything:

// Don't do this
func (a *Agent) HandleEverything(input string) string {
    // Check if it needs to search
    // Check if it needs to calculate
    // Check if it needs to save
    // Check if it needs to call API
    // ...you get the idea
}

This is what I call the "god agent" pattern. It works for demos, but falls apart in production. Why? Because single agents lack perspective. They're trying to be everything at once.

The Agency Approach

An agency is different. Think of it like a team:

// This is the way
type Agency struct {
    Planner    *Agent // Decides the steps
    Researcher *Agent // Searches and gathers info
    Coder      *Agent // Writes and reviews code
    Executor   *Agent // Runs tools and APIs
}

Each agent has a single responsibility. The planner doesn't code. The coder doesn't execute. The executor doesn't plan. They specialize, communicate, and together they solve problems that would overwhelm any single agent.

Why This Matters for Navi

When I started designing Navi, I made the agent mistake first. I built a monolithic agent that tried to handle orchestration, tool execution, memory management, and response formatting all at once.

It was a mess.

The breakthrough came when I realized: Navi isn't an agent. Navi is an agency. It's a system where specialized agents work together, each with clear boundaries and purposes.

Aspect	Agent	Agency
Scope	Single task	Coordinated workflow
Decision Making	Reactive	Strategic + Reactive
Failure Mode	All or nothing	Graceful degradation
Scalability	Limited	Horizontal
Maintenance	Hard to debug	Clear responsibility

The moment you understand this difference, your entire approach to AI orchestration changes. You stop asking "How do I make my agent smarter?" and start asking "How do I make my agents work better together?"

That's the foundation Navi was built on.

LLM Weaknesses

I love this tech. I studied it. I built with it. I'm building Navi on top of it. But here's the thing I learned the hard way: if you don't understand where LLMs break, you're not building infrastructure — you're building a house of cards.

Let me share what I discovered after countless debugging sessions at 4 AM.

The Context Wall That Nobody Talks About

Everyone celebrates bigger context windows like we solved everything. Cool, but here's what actually happens: your model starts forgetting stuff before it even hits the limit.

I was building this feature where Navi needed to remember conversation history plus tool results plus system instructions. Sounds simple, right? Well, around token 8,000 on a 32K model, things got weird. The model would:

Ignore instructions I placed at the beginning
Start giving generic answers
Hallucinate more frequently
Lose track of constraints

It's like when you study for 8 hours straight and by hour 7 you're just... reading words without absorbing anything.

// What I thought would work
func BuildContext(history, tools, instructions string) string {
    return instructions + history + tools // Simple concatenation, right?
}

// What actually happens inside the model
// Attention dilution = 📉

The lesson? More context ≠ more intelligence. Sometimes more context = more confusion.

The Confidence Problem

LLMs have no idea when they're wrong. None. Zero. They'll tell you the most confidently incorrect answer with 99% certainty.

I built a test where I asked the same question 100 times with slight variations. The model would give contradictory answers, each time sounding absolutely certain. That's when it hit me: confidence ≠ correctness.

type LLMResponse struct {
    Answer     string
    Confidence float64 // This number means nothing
    IsCorrect  bool    // The model doesn't know this
}

If you're building systems that execute code, handle money, or touch security — and you're trusting self-reported confidence — buddy, you're gonna have a bad time.

The Memory That Isn't There

LLMs don't have memory. They don't learn from conversations. They don't update their knowledge. After every response, it's like they're born again — pure amnesia with swagger.

Everything you think is "memory" is actually built by the developer. Without external memory architecture, you have a goldfish with a PhD. Brilliant, but forgets everything in 3 seconds.

The Generalist Trap

LLMs know everything and nothing at the same time. Ask about Kubernetes, quantum physics, anime plot lines, and medieval history in the same conversation? No problem. But dig deeper on any single topic, and you'll find the limits.

They're statistical generalists. Pattern matchers on steroids. Which is incredible for breadth, but dangerous when you need depth.

I learned this when I was vibe coding with active reviewing using Claude Opus models. It was generating code that looked perfect but had subtle bugs. The model knew the syntax, understood the pattern, but missed the edge cases because it doesn't actually understand code — it predicts tokens based on patterns it's seen.

The Hallucination Reality

Let's be clear: hallucination isn't a bug, it's a feature. Well, not really a feature, but an inevitable byproduct of how these models work. They predict tokens probabilistically. Sometimes that prediction is wrong. And they have zero idea when it happens.

What makes it worse:

Ambiguous instructions
Conflicting context
Too much information
Questions about things that don't exist

// The scary part
response := model.Ask("Something that doesn't exist")
fmt.Println(response)              // Returns something plausible
fmt.Println(model.KnowsItsWrong()) // false - method doesn't exist

Why Multi-Agent Systems Actually Matter

So why all this talk about weaknesses? Because understanding them changes everything about how you build.

Most people think multi-agent systems are about speed. Parallelization. Getting things done faster. They're wrong.

It's about cognitive distribution.

When I split Navi into specialized agents, something interesting happened:

Single Agent	Agency
Context dilution	Focused context per agent
High hallucination rate	Lower per-agent hallucination
Hard to debug	Clear failure boundaries
Generic responses	Specialized outputs
Everything fails together	Graceful degradation

Each agent operates in a smaller cognitive scope. Smaller scope means less confusion, better instruction adherence, and easier debugging.

// Before: One agent trying to do everything
type GodAgent struct {
    // Planning
    // Research
    // Coding
    // Execution
    // Verification
    // Memory
    // Everything...
}

// After: Specialized agents
type Agency struct {
    Planner    *Agent // Just plans
    Researcher *Agent // Just researches
    Coder      *Agent // Just codes
    Executor   *Agent // Just executes
    Verifier   *Agent // Just verifies
}

An agency isn't necessarily faster by default. It's more stable. Speed is a side effect. Stability is the goal.

The Hexagonal Architecture Decision

The AI landscape is in constant flux. New API versions, model capabilities, providers, and technologies emerge every month.

So how does this connect to architecture? Simple: if LLMs are inherently volatile and the AI field evolves so rapidly, your architecture needs to be decoupled to protect your system from these shifts.

Hexagonal architecture (ports and adapters) gives me:

Clear boundaries between LLM logic and business logic
Testable interfaces without calling actual models
Swappable implementations (swap implementations without changing core)
Isolation of hallucination-prone components

// Port: What the LLM can do
type LLMPort interface {
    Generate(ctx context.Context, prompt Prompt) (Response, error)
    Embed(ctx context.Context, text string) (Vector, error)
}

// Adapter: How we actually do it (OpenAI, Anthropic, local, etc.)
type OpenAIAdapter struct {
    client *openai.Client
}

// Core: Business logic that doesn't care which LLM
type Orchestrator struct {
    llm LLMPort
    // Doesn't know or care about the implementation
}

This isn't just clean code — it's survival. Let me be real about what can change in the next 12 months:

Technology changes — OpenAI changes their API. Anthropic launches a new protocol. Your architecture determines if this is a Tuesday afternoon config update or days of rewrites.
Fallback scenarios — OpenAI goes down. Rate limits hit. Your API key gets throttled. Hexagonal architecture means your orchestrator doesn't care — it just calls the port, and the adapter handles the failover.
Hybrid deployments — Some agents run locally for privacy, others in the cloud for power. Some use OpenAI, others use Claude, others use open-source models you host yourself. Same interface, different adapters.

// The orchestrator doesn't know or care
type Orchestrator struct {
    llm LLMPort
    // Could be OpenAI
    // Could be Anthropic
    // Could be your local Ollama instance
    // Could be a load balancer across 5 providers
    // Doesn't matter. Interface stays the same.
}

This is why hexagonal architecture isn't overengineering — it's acknowledging that the LLM landscape will change. The question isn't if you'll need to adapt. It's whether your architecture lets you adapt in hours or months.

What I Learned

LLMs are tools, not thinkers — They're incredibly powerful pattern matchers, but they don't "understand" like we do.
Architecture matters more than ever — Bad architecture with LLMs doesn't just break, it breaks unpredictably.
Specialization beats generalization — Both for agents and for the systems that contain them.
Human oversight is non-negotiable — No matter how autonomous your system is, keep humans in the loop for critical decisions.
The hype cycle is real — Ignore the "AI will replace developers" noise. Build useful things. Solve real problems.

What's Next for Navi

I'm still early in this journey. The architecture is stabilizing, but there's still so much code to write and decisions to make, like:

Sandbox
Memory management with vector stores
Security layers against prompt injection
Observability for agent interactions
Self-healing workflows
Human-in-the-loop interfaces

But the foundation is solid. And it's solid because I designed it around LLM weaknesses, not their strengths.

If you're building with LLMs, I'd love to hear your war stories. What architectural mistakes did you make? What worked? What completely failed?

Hit me up in the comments, on X or Discord. And if you're curious about Navi's progress, the GitHub repo is where all the messy experimentation happens in public (there's no code yet, but soon).

Remember: infrastructure survives bubbles. Hype doesn't. Build the former.

I'm building Navi: a truly secure and useful AI orchestrator | cry about it openclaw

Ênrell — Thu, 26 Feb 2026 08:50:25 +0000

Hello world guys!

The TL;DR is: I've tested openclaw and other AI orchestrators, and they always follow the exact same pattern:

They are built as products to be sold, not as open-source projects for the community. They are created by the hype and for the hype, pushing a generic idea of "agency"—a bloated product with a bunch of features and skills that, at the end of the day, aren't even that useful. That's because they aren't built to solve real problems; they're built for marketing and to sell big tech subscriptions.
That's exactly why OpenAI hired Peter Steinberger—a classic acqui-hire just to have another avenue to sell their API keys and subscriptions, not to solve actual problems.

I can name a few projects that follow this exact pattern:

Windsurf
Adept
Covariant

All hyped up as the "next generation of agents/coding/robotics". Google, Amazon, and Meta swoop in with licensing deals and poach the founders/team.

The result? The startups turn into ghost companies or run on skeleton crews. Employees cry in all-hands meetings, and the product dies or fades into irrelevance while the team goes off to work on big tech clouds/models.

Navi's differentiator

Navi's purpose is to be a useful, secure agent orchestrator built for the tech/dev community.

I've pointed out some useless aspects of openclaw, and you might be wondering why I'm thrashing openclaw specifically instead of other AI orchestrators. The answer is simple: because openclaw is the most popular, the most hyped, the most sold, and the most used right now. It’s the perfect example. Anyone in the tech bubble who hasn't heard of openclaw in the last few weeks has been living under a rock.

I won't deny that I'm in a bubble, that LLMs form a bubble that could pop at any minute, and that an AI winter will arrive sooner or later. But my point is: even if it is a bubble, even with all the hype and massive big tech investments, some companies will survive and open-source models will stick around. That's because there is real value and real demand; it's just not the kind of value and demand big tech is trying to sell. It's a more niche, specific, real, and useful demand. And that’s Navi's goal: to survive the bubble bursting.

I believe the bubble will pop, and the companies that survive will be the ones actually delivering value, whether that's a product, a service, or foundation models.
LLMs are highly useful technologies, especially in these areas (in no particular order):

The utility of agents

Software Development: It has never been easier to get a project off the ground. Testing ideas, learning a new framework, or just doing some "vibe coding" to see if a product holds up has become absurdly fast. The trap here is for those who just copy and paste without understanding what's going on under the hood. (If you want to avoid that and learn something useful, check out this post: how to use LLMs the right way).

Headache-free Customer Support: Forget those dumb bots from the past. A smart agent integrated into WhatsApp or internal systems handles 60% to 80% of the daily grind, 24/7. I have friends who have worked in support, and the reality is: 90% of issues are mundane things, often from the elderly or people with zero digital literacy. AI handles this without breaking a sweat.

Sales and Marketing at scale (without sounding like a robot): You can automate everything from lead qualification (SDR agents) to abandoned cart recovery and call analysis. It’s about generating content and sending personalized mass emails that actually sound natural.

Finding things within the company (the famous RAG): You know that massive legacy documentation or internal policies nobody knows where to find? Point an internal chat at it. If implemented well, documenting and querying company knowledge becomes trivial.

Cybersecurity and Blue/White Hats: Parsing logs by hand is boring and repetitive. A well-tuned model can chew through logs, detect threats, run superficial pentests, and generate reports in no time. It's an absolute lifesaver for security folks who need to reduce incident response times.

Despite all the benefits agents bring, most people have an exaggerated view of them and, more often than not, give them superpowers they shouldn't have. The catch is thinking that agents can solve everything. That couldn't be further from the truth: they should be part of the process, not take over the entire process.

Security

One of the saddest things in the tech bubble right now is the sheer negligence regarding security. It doesn't need to be enterprise-grade, but it has to be solid; have a minimum level of responsibility.
Don't be like certain devs: don't deploy a hobby project with open ports, plaintext credentials, and 1-click Remote Code Execution. Even explicitly warning people multiple times isn't enough—it's a recipe for disaster.

The Navi project

After that extensive rant, it's time to talk about the project that's been pulsing in my mind: Navi. The idea came to me years ago as a personal project (I'm clearly late to the party, right? XD). I've always looked for ways to automate my dev environment, whether it was self-hosted apps, CLI tools, or automation scripts, but I was never satisfied with how the automation was done, and I figured out why.

Task automation, especially on Linux, is extremely decentralized. This means we have plenty of automation tools, but they don't communicate natively or in a standardized way. You have a bash script for one thing, a cronjob for another, and several excellent CLI tools that require you to write ugly "glue code" just to make them talk to each other. The tools don't talk to each other, and they shouldn't, for security reasons.

Navi was born exactly to be that link, the maestro of this orchestra, but with one golden rule: you are always in control, and security is non-negotiable. It's not a "magical autonomous agent" that will run rm -rf / because it hallucinated mid-task or misinterpreted a loose prompt.

The name comes from NAVI, a computer from the anime Serial Experiments Lain (1998). It's one of my favorite anime and I highly recommend it: it's dense, intellectual, and philosophical. Anyway, this computer is used by the protagonist, Lain, to access the Wired (the ultra-advanced global network in the anime, sort of like an internet that mixes virtual reality, collective consciousness, and much more). NAVI is the hardware + software bundle to access the Wired. It features both navigation-based and voice-based interfaces.

NAVI:

She does an insane upgrade to her NAVI:

Navi's Architecture

To ensure the project is robust, scalable, and above all, testable, I chose to write Navi in Go. Besides delivering absurd performance and compiling everything into a single binary (which makes life on Linux so much easier), Go allows me to handle concurrency in a very elegant and straightforward way.

The foundation of the project follows the Hexagonal Architecture (Ports and Adapters).

This means Navi's core intelligence and orchestration are completely isolated from external tools and interfaces. If tomorrow I want to swap out the LLM provider, the local database, or how it executes a script on my OS, I just write a new "adapter". The business logic remains intact and isolated from side effects.

How do you interact with it?

As I mentioned at the beginning, Navi doesn't lock you into a heavy, proprietary web UI that tries to shove a subscription down your throat, nor is it an agent that will expose your credentials. It was designed to have multiple entry points (the Ports in our architecture):

TUI (Terminal User Interface): For terminal dwellers (and anyone who uses Neovim and a window manager like Sway knows the value of never having to take your hands off the keyboard), having a fast, beautiful, and responsive interface right in the console is essential.

REST/gRPC API: If you want to integrate Navi into another system, build your own frontend, or trigger webhooks from other applications, the door is open.

Messaging Bots: Native integration with Discord and Telegram. You can trigger automations on your server or your home machine by sending a text from your phone, in a secure and authenticated way.

The roadmap is still being drawn up, and the core is currently under development. The goal is to build something open-source, focusing on solving real productivity and system orchestration problems, without selling our souls to the hype.

I'll be dropping the GitHub repository soon for anyone who wants to take a look at the code (or chip in on the PRs). Until then, we keep coding!

-- Present day, present time! hahahahaha

AnimeSubs an LLM Subtitle Translator

Ênrell — Tue, 02 Dec 2025 21:11:22 +0000

Hey guys, I want to share with you this application that I build to solve one problem that is common on original anime blue-rays - The lack in the native subtitles (Brazilian Portuguese for my case).

The problem

Most media content on the internet is in English, Anime episodes included. I consider myself proficient on English, I can write, read, listening and speak but is not my native language, I’m from Brazil my native language is Portuguese. But, if I can read the Anime subtitle on English — What is the problem with that? — Comfort. I can read the subtitle on English, but my vocabulary is short, and limited by technical English, that is the content that I consume more, so, if some word that I don’t know appears on subtitle, I have to stop the episode, and translate, this break the attention, in my native language is more comfortable and fun to watch.

Ways to solve

There are some ways to solve this problem, the most common is to download subtitle files from the internet, there are many sites that provide subtitle files in many languages, but this approach has some problems:

Not all animes have subtitles in all languages, some animes are very niche and don’t have subtitles in many languages.
The quality of the subtitles is not guaranteed, some subtitles are poorly translated, or have many errors.
The timing of the subtitles may not match the video, causing a bad experience.
It requires manual effort to find, download and sync the subtitles with the video.

Another way to solve this problem is to use machine translation services, like Google Translate, DeepL, etc. But this approach also has some problems:

The quality of the translation is not always good, especially for complex sentences or idioms.
The context of the dialogue may be lost, leading to awkward or incorrect translations.
It may require internet connection, which is not always available.

The solution: AnimeSubs

To solve this problem, I decided to build an application that uses Large Language Models (LLMs) to translate anime subtitles from any language to any other language that the model supports. The application is called AnimeSubs, and it works as follows:

Requirements: mkvmerge (part of mkvtoolnix) and ffmpeg must be installed and available in the system PATH.

Note: The application is in its early stages, may you encounter some bugs (mainly on Windows and Mac, I do not focus on those platforms right now), this is my first desktop application using Tauri, so, please, report any issues on the GitHub repository.

Download animesubs here: AnimeSubs

The user provides the video file or folder containing the video files and the LLM provider.

Select the source and target languages for the translation.

Select the output type for subtitles (ass, srt or vtt)

After configuring the settings, the user can start the translation process.

Is very important to select the use mkvmerge for muxing the subtitles into the video file.
Because ffmpeg have some issues with subtitle muxing.
If you do not select mkvmerge, the subtitles may not work.

You can add a custom prompt to, for example, if I just keep the default english -> portuguese prompt, the model can mix Portugal portuguese and Brazilian portuguese, the two are correct, but have different nuances, so you may want to specify which one you prefer.

If you want to select some specific subtitle track, select manually.

Click on start translation button and wait for the process to finish (do not close the app on muxing process).

Conclusion

AnimeSubs is a powerful tool for translating anime subtitles using LLMs. It addresses the common issues faced by anime fans who struggle with language barriers and provides a more comfortable viewing experience. By leveraging the capabilities of modern AI, AnimeSubs can deliver high-quality translations that respect the nuances of different languages and cultures.
I hope you find this application useful and enjoy watching anime or other media in your native language! If you have any questions or feedback, feel free to reach out to me on GitHub. Happy watching!

Note: AnimeSubs is licensed under the AGPL-3.0 License.

Git + GitHub para iniciantes

Ênrell — Tue, 26 Dec 2023 13:22:37 +0000

O que é GitHub?

O GitHub é uma plataforma de desenvolvimento baseada em Git. Na prática, ele funciona como um grande hub onde desenvolvedores armazenam código, colaboram em projetos e automatizam processos relacionados ao desenvolvimento de software. Ele é utilizado tanto por pessoas físicas quanto por empresas, em projetos pequenos ou de grande escala.

Apesar de ser a plataforma mais conhecida, o GitHub não é a única solução disponível. Existem outras plataformas que oferecem ferramentas semelhantes, como SourceForge, Bitbucket, GitLab — que não pertence à Microsoft e não é um complemento do GitHub — e o GNU Savannah, voltado principalmente para projetos de software livre.

Ferramentas

Uma das funcionalidades centrais do GitHub é o sistema de armazenamento de código por meio dos chamados repositórios. Os repositórios são responsáveis por guardar o código-fonte de uma aplicação de forma segura, versionada e distribuída.

Por utilizar o Git como base, o GitHub herda um modelo de controle de versão distribuído. Isso permite que várias pessoas trabalhem no mesmo projeto ao mesmo tempo, cada uma com sua própria cópia do repositório, sem que o trabalho de uma interfira diretamente no da outra.

Além do versionamento, o GitHub facilita bastante a colaboração entre desenvolvedores. É possível contribuir com projetos, propor alterações no código, revisar mudanças feitas por outras pessoas e discutir decisões técnicas diretamente na plataforma.

Outro ponto importante é o rastreamento de problemas. As chamadas issues são usadas para organizar tarefas, registrar bugs, planejar melhorias e centralizar discussões relacionadas ao projeto. Isso ajuda muito na comunicação e na organização do trabalho, principalmente em equipes.

Quando alguém propõe uma alteração no código, normalmente isso é feito por meio de um pull request. Esse recurso permite que o código seja revisado antes de ser incorporado ao projeto principal, reduzindo erros e melhorando a qualidade do software.

O GitHub também oferece suporte à integração contínua. Isso significa que é possível configurar processos automatizados para testar, validar e construir o código sempre que uma alteração é enviada ao repositório. Dentro desse contexto, o GitHub Actions se destaca como uma ferramenta nativa que permite automatizar fluxos de trabalho como testes, build e deploy diretamente na plataforma.

Outro detalhe importante é o licenciamento. A maioria dos repositórios inclui um arquivo LICENSE, que define como o código pode ser usado, modificado e redistribuído por outras pessoas. Isso é essencial tanto para projetos open source quanto para projetos privados.

É seguro?

O GitHub adota diversas práticas de segurança para proteger tanto os usuários quanto os projetos hospedados na plataforma.

Uma das formas mais comuns de autenticação é o uso de chaves SSH. Esse método utiliza um par de chaves, uma pública e uma privada. A chave pública é associada à sua conta no GitHub, enquanto a chave privada permanece apenas no seu computador. A autenticação acontece sem que você precise informar sua senha a cada operação.

Além disso, o GitHub permite configurar permissões de acesso nos repositórios. É possível definir quem pode apenas visualizar o código, quem pode enviar alterações e quem pode administrar o projeto. Isso garante que apenas pessoas autorizadas tenham acesso a determinadas ações.

A plataforma também oferece autenticação em dois fatores, adicionando uma camada extra de segurança ao exigir uma segunda forma de verificação além da senha. Somado a isso, o GitHub mantém políticas de segurança ativas, monitorando atividades suspeitas e aplicando medidas para reduzir riscos.

Outro ponto relevante é a realização de backups regulares, que ajudam a evitar perda de dados em caso de falhas na infraestrutura.

Como criar um repositório no GitHub?

A forma mais indicada de criar um repositório é diretamente pelo site do GitHub. O processo é simples e guiado.

Durante a criação, você define o nome do repositório, que deve conter apenas letras, números e alguns caracteres especiais como ponto, hífen ou underline. Também é possível adicionar uma descrição, que ajuda outras pessoas a entenderem rapidamente o objetivo do projeto.

É altamente recomendável criar o repositório já com um arquivo README. Esse arquivo funciona como a porta de entrada do projeto, explicando o que ele faz, como usar e, em muitos casos, como contribuir.

Caso você já tenha um projeto pronto no seu computador, o fluxo costuma ser criar o repositório com o README, clonar esse repositório localmente, copiar os arquivos do projeto para dentro da pasta clonada e então enviar tudo para o GitHub com um push.

Importando um projeto e enviando para o GitHub

Antes de enviar código para o GitHub de forma segura, o ideal é configurar a autenticação via SSH. Para entender melhor os conceitos envolvidos, vale a pena ler um material introdutório sobre SSH.

O primeiro passo é gerar um par de chaves SSH. O algoritmo recomendado atualmente é o ed25519, por ser mais moderno e seguro. Isso pode ser feito com o seguinte comando:

ssh-keygen -t ed25519

Durante o processo, o sistema perguntará onde a chave deve ser salva. Na maioria dos casos, manter o caminho padrão é a melhor escolha. Se quiser, você pode apenas alterar o nome do arquivo. Esse arquivo será sua chave privada e não deve ser compartilhado com ninguém.

Em seguida, você deverá definir uma senha para proteger essa chave. Essa senha será solicitada sempre que a chave for utilizada, então é importante não esquecê-la. O uso de um gerenciador de senhas é altamente recomendado.

Após isso, o sistema criará automaticamente a chave pública, que terá a extensão .pub e ficará no mesmo diretório da chave privada.

Durante a geração da chave, também será exibido um fingerprint. O fingerprint é uma representação curta e única da chave SSH, usada para verificar sua autenticidade. Como estamos apenas criando uma chave local, essa informação não exige atenção especial neste momento.

Com a chave criada, basta copiar todo o conteúdo da chave pública e adicioná-la nas configurações da sua conta no GitHub, na seção de chaves SSH. Nessa etapa, você define um nome para a chave e cola o conteúdo copiado no campo correspondente.

Depois disso, sua conta estará configurada para autenticação via SSH.

Clonando repositórios via SSH

Com a chave SSH configurada, você pode clonar repositórios utilizando a URL SSH fornecida pelo GitHub. A partir desse momento, será possível enviar commits para o repositório remoto de forma segura, sem a necessidade de informar usuário e senha a cada operação.

Esse fluxo torna o uso do Git mais prático e alinhado com as boas práticas de segurança adotadas atualmente.

Próximos capítulos

No próximo capítulo, vamos sair um pouco da prática e mergulhar na teoria do Git. A ideia é explicar como o controle de versão funciona e como os conceitos que usamos hoje surgiram e evoluíram ao longo do tempo.

SSH para iniciantes

Ênrell — Tue, 26 Dec 2023 13:21:03 +0000

O que é SSH?

Descrito no documento oficial do SSH como:

" The Secure Shell (SSH) Protocol is a protocol for secure remote login
and other secure network services over an insecure network."

"O Protocolo Secure Shell (SSH) é um protocolo para login remoto seguro e outros serviços de rede seguros sobre uma rede não segura."

Resumindo, é um protocolo de rede criptografado usado para comunicações seguras em uma rede não segura. Ele permite que usuários acessem e controlem remotamente dispositivos e servidores pela internet de forma segura.

O SSH fornece uma maneira segura de autenticar e trocar dados criptografados entre dois sistemas, prevenindo potenciais ameaças de interceptação ou manipulação de dados durante a transmissão. Isso é particularmente crucial ao acessar servidores remotos ou realizar tarefas administrativas em sistemas distribuídos.

Como SSH é um protocolo de rede, não uma ferramenta, temos que baixar uma ferramenta que nos disponha dos recursos necessários para usar o SSH.

No nosso caso vamos usar a "suite" (conjunto de ferramentas) OpenSSH, que é uma implementação de código aberto do protocolo SSH, em conjunto com ferramentas essenciais para nós desenvolvedores, todo desenvolvedor deve estudar SSH e Criptografia, é indispensável.

Vamos começar criando um par de chaves SSH com a ferramenta "ssh-keygen".

Para criar um par de chaves SSH usando um algoritmo moderno e rápido como o "ed25519" só precisamos passar o parâmetro "-t" para o gerador, e ele lhe guiará para a criação do par de chaves ssh-keygen -t ed25519.

Mas o que é esse tal de "ed25519"?

O "ed25519" é um sistema de chaves públicas de curvas elípticas de utilizado para criptografia assimétrica, onde um par de chaves é gerado: uma chave privada e uma chave pública. Ele faz parte de uma família de curvas elípticas chamada "Curve25519", desenvolvida pelo renomado matemático Daniel J. Bernstein no ano de 2011. O algoritmo "ed25519" oferece vantagens significativas de segurança e desempenho sobre algoritmos mais antigos como o RSA e SHA-256.

Chaves assimétricas

Chaves assimétricas, também conhecidas como criptografia de chave pública, são um tipo de sistema de criptografia que utiliza um par de chaves relacionadas, composto por uma chave pública e uma chave privada. Essas chaves são matematicamente relacionadas, mas as informações codificadas com uma chave só podem ser decodificadas pela outra chave do par. Isso significa que o que é criptografado com a chave pública só pode ser descriptografado pela chave privada correspondente, e vice-versa.

Chave Pública: Essa chave é geralmente distribuída livremente e conhecida por todos. Ela é usada para criptografar informações que só podem ser decodificadas pela chave privada correspondente.
Chave Privada: Esta chave é mantida em segredo e protegida pelo proprietário. É usada para descriptografar as informações que foram criptografadas com a chave pública correspondente.

O uso de chaves assimétricas é fundamental em vários aspectos da segurança digital, como autenticação, assinaturas digitais e troca segura de chaves de sessão em protocolos como o SSH (Secure Shell) e o SSL/TLS (usado para comunicação segura na web).

Um exemplo comum de aplicação é quando você acessa um site seguro (usando HTTPS). O servidor web possui uma chave privada que corresponde a uma chave pública incorporada no certificado SSL. Quando você envia informações para o servidor, a conexão é criptografada usando a chave pública no certificado, e apenas o servidor, com a chave privada correspondente, pode descriptografar essas informações. Isso garante a confidencialidade e a integridade dos dados transmitidos.

Conclusão

Em conclusão, o SSH desempenha um papel fundamental na garantia da segurança das comunicações em redes, especialmente quando se trata de acesso remoto a dispositivos e servidores. Ao utilizar o protocolo SSH e implementar chaves assimétricas, como o algoritmo "ed25519", os desenvolvedores podem estabelecer conexões seguras, prevenindo ameaças de interceptação ou manipulação de dados durante a transmissão.

A escolha do algoritmo "ed25519" destaca a importância de algoritmos modernos e eficientes em comparação com métodos mais antigos. As chaves assimétricas desempenham um papel crucial na criptografia de chave pública, possibilitando autenticação segura, assinaturas digitais e a troca segura de informações em diversas aplicações, incluindo protocolos como SSH e SSL/TLS.

No contexto do desenvolvimento, a utilização da suite OpenSSH e a compreensão dos princípios de criptografia, incluindo chaves assimétricas, são consideradas indispensáveis. A criação de pares de chaves SSH, como exemplificado com o comando "ssh-keygen -t ed25519", demonstra um passo inicial essencial para garantir a segurança nas comunicações e acessos remotos.

Em resumo, o SSH e as chaves assimétricas desempenham um papel crucial na construção de um ambiente de desenvolvimento seguro, protegendo a integridade e confidencialidade das informações transmitidas pela rede. O conhecimento e a aplicação adequada desses conceitos são essenciais para qualquer desenvolvedor comprometido com a segurança de seus sistemas e comunicações.

Git para iniciantes

Ênrell — Tue, 12 Dec 2023 21:28:50 +0000

Disclaimer

Leia tudo de forma sequencial, é importante não pular etapas. Algumas partes do texto dão o contexto necessário para o entendimento.

O que é Git?

No repositório do Git no GitHub os desenvolvedores do Git o definem como:

"É um sistema de controle de revisão rápido, escalável e distribuído, com um conjunto de comandos excepcionalmente rico que oferece operações em níveis elevados e acesso completo às partes internas."

O Git é um projeto de código aberto coberto pela Licença Pública Geral GNU versão 2 (algumas partes estão sob licenças diferentes, compatíveis com a GPLv2). Foi originalmente escrito por Linus Torvalds criador do Linux com a ajuda de um grupo de hackers ao redor da internet.

Por que usar Git?

Se você já se viu duplicando projetos e renomeando pastas para criar versões diferentes, sabe como isso pode complicar as coisas. Trabalhar assim em equipe aumenta os desafios.

O Git funciona como um histórico de alterações para o seu projeto. Em vez de modificar diretamente o projeto principal, você cria "ramificações" para experimentar ideias. Quando tudo estiver pronto, você "confirma" essas mudanças, criando um registro claro do que foi feito.

Isso não apenas mantém tudo organizado, mas também facilita a colaboração em equipe. Se outros estiverem trabalhando no projeto, o Git ajuda a juntar todas as mudanças de maneira tranquila.

Então, da próxima vez que pensar em fazer cópias e renomeações loucas, considere adotar o Git. Ele tornará seu projeto mais organizado, eficiente e colaborativo, sem aquela confusão toda.

Comandos básicos do Git

OBS: Alguns comandos deste tópico tem vantagens e desvantagens em serem usados, neste tópico não irei tratar delas, ficará para outro post.

git init

O primeiro comando básico que você vai usar é o git init, mas o que ele faz? para que serve?

O git init é usado para iniciar um novo repositório Git em um diretório existente ou em um novo diretório vazio. Ao executar git init, você está basicamente informando ao Git para começar a rastrear as alterações nos arquivos dentro desse diretório.

Quando você executa git init, alguns arquivos e diretórios específicos são criados dentro do diretório do seu projeto. O principal deles é o diretório oculto chamado .git, que contém toda a estrutura necessária para o Git controlar as versões dos seus arquivos.

NÃO EXCLUA A PASTA .git DE FORMA ALGUMA!
Se você fizer isso, apagará todo seu histórico de modificações do seu repositório local.

git config user.name e git config user.email

Os comandos git config user.name e git config user.email são usados para configurar o nome do usuário e o endereço de e-mail associados aos commits que você faz em um repositório Git. Essas informações são incluídas em cada commit para identificar quem fez as alterações. Esses comandos são um passo importante para a identificação da pessoa que fez o commit, fundamental para a comunicação da equipe. Você irá usar da seguinte forma: git config user.name (seu nome aqui), não esqueça de remover os (), a mesma sintaxe vale para o email.

git add

O comando git add é utilizado no Git para adicionar mudanças específicas em arquivos ao chamado "index" (ou "staging area") vou explicar esses termos mais tarde. Essa etapa é necessária antes de realizar um commit para registrar as alterações no histórico do repositório.

Quando você faz alterações em seus arquivos, o Git precisa saber quais dessas alterações você deseja incluir no próximo commit. O git add permite que você selecione as mudanças específicas que você quer incluir, preparando-as para o próximo commit. Você irá usar da seguinte maneira: git add (nome do seu arquivo com sua extensão).

git add . O comando git add . é utilizado para adicionar todas as mudanças que você fez ao "staging" (ou "área de preparação"), ou seja, todas as mudanças feitas nos seus arquivos serão preparadas para o commit.

Eu recomendo cuidado ao usar o comando git add ., por exemplo:

Imagine que você tenha feito a página "sobre.html" do seu projeto e também feito algumas mudanças na página "home.html". No entanto, você só deseja fazer o commit das alterações na página "sobre" para manter as coisas organizadas.

Se você usar git add ., você estará adicionando as mudanças tanto da página "sobre.html" quanto da "home.html" para o próximo commit, o que pode não ser o que você quer. Para evitar esse problema, é melhor usar git add sobre.html. Em seguida, você pode fazer o commit para registrar apenas as alterações na página "sobre.html" e manter seu histórico de versões mais preciso e organizado.

O que é Commit?

E finalmente, o tão citado commit, uma peça fundamental no uso do Git.

Em termos simples, um commit no Git representa uma captura instantânea do seu projeto em um determinado momento. É como tirar uma foto do estado atual dos seus arquivos, incluindo todas as alterações que você adicionou ao "staging area" (ou "área de preparação") com o comando git add.

Cada commit é associado a uma mensagem descritiva, que serve para explicar o propósito daquela alteração. Essas mensagens são cruciais para entender o histórico do seu projeto e facilitam a colaboração em equipe, já que outros desenvolvedores podem compreender suas mudanças apenas lendo as mensagens dos commits.

Como usar git commit -m "mensagem descritiva":

Após usar git add para preparar as alterações, o próximo passo é usar git commit para criar um commit.

Sintaxe básica:

  git commit -m "mensagem descritiva"

-m: Permite adicionar uma mensagem descritiva diretamente na linha de comando.

Dicas para mensagens de commit:

Seja Descritivo: A mensagem deve explicar o que a alteração realiza. Evite mensagens vagas como "correções" ou "mudanças".
Seja Conciso: Mantenha a mensagem curta e objetiva. Evite explicações excessivamente detalhadas.
Use o Presente: Mantenha a consistência no tempo verbal. Prefira o tempo presente, como em "Adiciona funcionalidade" em vez de "Adicionou funcionalidade".

Caso esteja disposto a aprender um padrão de commits recomendo o Conventional Commits.

Próximos capítulos

Para o próximo capítulo vou mostrar como usar o git juntamente com o GitHub.