Forem: Gustavo A. Gutkoski

Creating an AI Assistant for Technical Documentation – Part 2.1: Introduction to the Crawler

Gustavo A. Gutkoski — Mon, 26 May 2025 11:30:39 +0000

This post is also available in Portuguese: Read in Portuguese

In the previous post, I shared the motivation and idea behind Project Insight — an open source project I'm developing with the goal of building an intelligent assistant capable of understanding and documenting source code interactively.

In this post, we'll take a look at the first technical component of the project: the crawler.

What is the crawler and why is it important?

The crawler is the core of Project Insight’s static analysis phase. It’s responsible for:

Navigating through Java project files.
Identifying and extracting key information such as:
- Class and method names.
- Modifiers (public, private, etc).
- Return types.
- The line where each item appears in the code.

These details are stored in a local database and will later be used by the AI to answer project-related questions in a contextualized way.

Project structure overview

To keep the project clean and maintainable from the start, I structured the crawler into separate modules, each with a clear responsibility:

project-insight-crawler/
├── crawler/
│   ├── database/       # Database creation and connection (SQLite)
│   ├── logger/         # Centralized logger for the project
│   ├── models/         # Models for Java classes and methods
│   ├── parser/         # Parser that extracts data from .java files
│   ├── use_cases/      # Use cases like saving data to the database
│   └── __init__.py
├── tests/              # Unit tests for main modules
├── crawler.db          # Local SQLite database
├── main.py             # Project CLI interface
├── runner.py           # Main script to execute the crawler
├── LICENSE
├── Makefile
├── poetry.lock
├── pyproject.toml
├── README.md

This structure allows each part to evolve independently, keeping the codebase modular and testable.

Initial architecture decisions

From the beginning, I made some decisions to simplify development and ensure quality:

Language: Python, for its familiarity and fast prototyping capabilities.
Database: SQLite, lightweight and easy to set up — ideal for MVPs.
Dependency management: poetry, for streamlined installation and packaging.
Code quality tools: already set up with:
- ruff (linter and formatter)
- mypy (type checking)
- pre-commit hooks
Automation and maintenance:
- GitHub Actions: for running tests on every push.
- Dependabot: to keep dependencies safely up to date.

All of this helps maintain consistent code quality and reduces future headaches.

What’s next

In the next post (Part 2.2), I’ll dive deeper into how the parser works — reading .java files line by line, detecting relevant code blocks, and extracting the information that feeds the database.

What do you think?

If you enjoyed this post so far, feel free to follow me here on Dev.to to keep up with the rest of the Project Insight series. I'm building this in real-time, so any feedback, questions, or suggestions are more than welcome in the comments!

Link to the project: https://github.com/gustavogutkoski/project-insight-crawler

⚙️ This post was written with the help of an AI assistant for writing and editing. All ideas, project structure, and technical implementations are my own.

Criando um assistente com IA para documentação técnica – Parte 2.1: Introdução ao Crawler

Gustavo A. Gutkoski — Mon, 26 May 2025 11:27:18 +0000

Este post também está disponível em inglês: Leia em inglês

No post anterior, compartilhei a ideia e motivação por trás do Project Insight — um projeto open source que estou desenvolvendo com o objetivo de criar um assistente inteligente capaz de entender e documentar código-fonte de forma interativa.

Neste post, vamos fazer uma breve análise na primeira parte técnica do projeto: o crawler.

O que é o crawler e por que ele é importante?

O crawler é o coração da etapa de análise estática do Project Insight. Ele é responsável por:

Navegar pelos arquivos de um projeto Java.
Identificar e extrair informações importantes como:
- Nome de classes e métodos.
- Modificadores (public, private, etc).
- Tipo de retorno.
- Linha em que cada item aparece no código.

Esses dados são armazenados em um banco local e futuramente utilizados pela IA para responder perguntas sobre o projeto de forma contextualizada.

Estrutura inicial do projeto

Para manter o projeto bem organizado desde o início, estruturei o crawler em módulos separados, cada um com uma responsabilidade clara:

project-insight-crawler/
├── crawler/
│   ├── database/       # Criação e conexão com o banco (SQLite)
│   ├── logger/         # Logger centralizado para o projeto
│   ├── models/         # Modelos para classes e métodos Java
│   ├── parser/         # Parser que extrai dados dos arquivos .java
│   ├── use_cases/      # Casos de uso como salvar dados no banco
│   └── __init__.py
├── tests/              # Testes unitários para os módulos principais
├── crawler.db          # Banco de dados SQLite gerado localmente
├── main.py             # Interface CLI do projeto
├── runner.py           # Arquivo principal para execução do crawler
├── LICENSE
├── Makefile
├── poetry.lock
├── pyproject.toml
├── README.md

Essa organização permite que cada parte evolua de forma isolada, mantendo o código limpo e testável.

Decisões iniciais de arquitetura

Desde o início, tomei algumas decisões para facilitar o desenvolvimento e garantir qualidade:

Linguagem: Python, pela familiaridade e agilidade para prototipar.
Banco de dados: SQLite, por ser leve, simples de configurar e ideal para MVPs.
Gerenciador de dependências: poetry, para facilitar a instalação e empacotamento.
Qualidade de código: já estão configuradas ferramentas como:
- ruff (linter e formatter)
- mypy (type checking)
- Hooks de pre-commit
Automação e manutenção:
- GitHub Actions: para rodar testes automaticamente a cada push.
- Dependabot: para manter as dependências sempre atualizadas de forma segura.

Isso tudo ajuda a manter o padrão do código consistente e evita surpresas no futuro.

Próximos passos

No próximo post da série (Parte 2.2), vou mostrar em mais detalhes como funciona o parser que lê os arquivos .java linha por linha, identificando os blocos relevantes do código e extraindo as informações que alimentam o banco de dados.

E aí, o que achou?

Se curtiu o conteúdo até aqui, me segue aqui no Dev.to pra acompanhar os próximos posts sobre o Project Insight. Tô desenvolvendo tudo isso aos poucos e em tempo real, então qualquer sugestão, dúvida ou crítica é super bem-vinda nos comentários!

Link para o repositório: https://github.com/gustavogutkoski/project-insight-crawler

⚙️ Este texto foi escrito com o apoio de uma IA como assistente de escrita e revisão. Todas as ideias, estrutura do projeto e implementações técnicas são de autoria própria.

Creating an AI Assistant for Technical Documentation – Part 1: Why and How I Started This Project

Gustavo A. Gutkoski — Fri, 09 May 2025 13:18:40 +0000

This post is also available in Portuguese: Read in Portuguese

Hello! I'm Gustavo — a back-end software developer with a passion for Java, Python, automation, software design, and more recently, using AI for practical application. I'm beginning my technical writing here, sharing some of the knowledge and experience derived from projects that I've been developing myself.

I've also always been a learn-by-doing kind of person — break things, repair them, and work with actual issues. So in addition to picking up new tools, I thought I'd blog the experience along the way — perhaps it's helpful to someone out there, or at least provokes some interesting discussions in here.

The Project: an AI Assistant for Technical Documentation

Ever feel lost in oceans of technical documentation, or spend too much time wondering how a codebase really works?

That's what surprised me — and made me curious to learn more about AI, automation, and architecture — and prompted me to begin a side project: a smart assistant that can comprehend the structure of a Java project and respond to questions in the style of an "internal team chat."

Why I Started This Project

The concept arose while developing the TrustScore API, a Java Spring Boot product review application. I wondered how it was feasible to automate code base comprehension, besides discovering AI concepts applied to software development.

It also served as a great opportunity to hone:

Python and FastAPI for real projects
Data extraction and structuring
Data-oriented architecture and API design
Source code integration and AI

Project Overview

The plan is to create a system whereby an AI assistant can respond to inquiries regarding the code of a project. To this end, I laid out the following steps:

Crawler: a script that crawls .java files, extracting class names, methods, attributes, and their corresponding comments.
Storage: all the data is organized and saved in a local SQLite database.
API with FastAPI: a REST API displays the data extracted in a well-formatted way.
AI Agent: an LLM will use the API data to respond in a natural way.
Interface: a basic chat-style front-end to communicate with the AI.

First Steps: Creating the Crawler

Before any AI can respond to questions about a codebase, it must first know what's in there. So I began by creating a basic Python crawler to learn the layout of the Java application I had created (the TrustScore API).

Its purpose was to obtain large amounts of information from .java files, i.e.:

names of classes and their locations;
methods, their signatures, and related comments;
applicable variables and attributes.

My idea was a straightforward line-by-line file read with some regular expressions. Nothing too complicated — just the goal was to get something working reasonably quickly and locally, without needing to use larger external libraries.

Data scraped is stored in a SQLite database, formatted in a way that will facilitate future querying. The database will act as the baseline for the future steps — particularly for the API and subsequent AI integration.

Soon to come is a special post on how I constructed this crawler from scratch — step-by-step process, challenges, and how I approached the data structure.

GitHub Repository: https://github.com/gustavogutkoski/ProjectInsight

Next Steps

Currently, I am trying to create the API using FastAPI to expose the code data obtained. The goal is to have this API prepared to be consumed by an AI agent in the near future.

After that, I plan to:

Add an LLM to provide context-based answers
Create a simple front-end with a chat-like interface
Enrich the retrieved information to add question context

Wrapping Up

This project has been both a technical and artistic challenge — taking code scraping, REST APIs, and AI concepts and turning them into something that could be truly useful in the everyday workflow of any dev team.

In future posts, I'll delve more into the way I'm constructing the API and then how I intend to add an AI model to it all.

I'm always receptive to ideas, suggestions, and feedback!

Follow me here on Dev.to to keep up to date for the next parts of this series.

⚙️ This text was written with the support of an AI assistant for writing and editing. All ideas, project structure, and technical implementations are my own.

Criando um assistente com IA para documentação técnica – Parte 1: Por que e como comecei esse projeto?

Gustavo A. Gutkoski — Fri, 09 May 2025 13:14:55 +0000

Este post também está disponível em inglês: Leia em Inglês

Oi! Eu sou o Gustavo — desenvolvedor back-end, apaixonado por Java, Python, automações, arquitetura de software e, mais recentemente, por aplicar IA em projetos práticos. Resolvi começar minha jornada de escrita técnica por aqui, compartilhando um pouco das experiências e aprendizados com os projetos que venho criando por conta própria.

Sempre acreditei que a melhor forma de aprender é botando a mão na massa: errando, ajustando e resolvendo problemas do mundo real. Então, além de explorar novas ferramentas, decidi também documentar esse caminho — vai que isso ajuda alguém ou rende boas conversas por aqui.

O projeto: um assistente com IA para documentação técnica

Já se sentiu perdido em meio a uma documentação extensa ou teve dificuldade para entender como uma base de código realmente funciona?

Foi pensando nisso — e querendo aprender mais sobre IA, automações e arquitetura — que comecei a desenvolver um projeto pessoal: um assistente inteligente capaz de entender a estrutura de um projeto em Java e responder perguntas como se fosse um “chat interno” da equipe.

Por que criei esse projeto?

A ideia surgiu durante o desenvolvimento da TrustScore API, uma aplicação em Java com Spring Boot para avaliação de produtos. Eu queria explorar maneiras de automatizar o entendimento da base de código e, ao mesmo tempo, estudar conceitos de IA aplicada ao desenvolvimento de software.

Também vi aí uma ótima oportunidade para praticar com:

FastAPI e Python em projetos reais
Estruturação e extração de dados
Design de APIs e arquitetura orientada a dados
Integração entre IA e código-fonte

Visão geral do projeto

O objetivo é criar um sistema em que um assistente com IA possa responder perguntas sobre o código de um projeto. Para isso, defini os seguintes passos:

Crawler: script que varre arquivos .java e extrai nomes de classes, métodos, atributos e comentários relevantes.
Armazenamento: os dados são organizados e salvos em um banco SQLite local.
API com FastAPI: uma API REST que expõe os dados extraídos de forma estruturada.
Agente de IA: um modelo de linguagem (LLM) que utilizará os dados da API para responder perguntas de forma natural.
Interface: um front-end simples em formato de chat para interagir com a IA.

Primeiros passos: construindo o crawler

Antes de qualquer IA começar a responder perguntas sobre um código, ela precisa entender o que existe ali dentro. Por isso, comecei criando um crawler simples em Python para analisar a estrutura da aplicação Java que desenvolvi (a TrustScore API).

A ideia era extrair informações importantes dos arquivos .java, como:

nomes de classes e onde aparecem
métodos, suas assinaturas e comentários associados
atributos e variáveis relevantes

A lógica foi implementada de forma simples: leitura linha a linha dos arquivos, utilizando expressões regulares. Nada sofisticado neste início — o foco era ter algo funcional rapidamente e que rodasse localmente, sem depender de bibliotecas externas mais pesadas.

Os dados extraídos são armazenados em um banco SQLite já estruturado para permitir consultas futuras. Essa base será essencial para os próximos passos do projeto — especialmente para alimentar a API e, depois, o modelo de IA.

Em breve, vou publicar um post detalhado explicando como criei esse crawler do zero — incluindo o passo a passo, os desafios e como pensei a estrutura de dados.

Repositório do projeto no GitHub: https://github.com/gustavogutkoski/ProjectInsight

Próximos passos

Agora estou trabalhando na criação da API com FastAPI para expor os dados extraídos do código. A ideia é deixá-la pronta para ser consumida por um agente de IA.

Depois disso, pretendo:

Integrar uma LLM para gerar respostas contextuais
Criar um front-end básico com interface de chat
Ajustar e enriquecer os dados extraídos para melhorar o contexto das respostas

Conclusão

Esse projeto tem sido um desafio técnico e criativo — unindo scraping de código, API REST e conceitos de IA em algo que pode ser útil no dia a dia de qualquer time de desenvolvimento.

Nos próximos posts, vou detalhar como estou implementando a API e, mais pra frente, como pretendo conectar um modelo de IA a tudo isso.

Fico aberto a sugestões, ideias e feedbacks!

Me segue aqui no Dev.to e acompanha os próximos capítulos dessa série.

⚙️ Este texto foi escrito com o apoio de uma IA como assistente de escrita e revisão. Todas as ideias, estrutura do projeto e implementações técnicas são de autoria própria.