How edivandosevero05/engenharia-de-software-com-ia-aplicada works
This repository is a course-oriented monorepo of independent example projects for “Engenharia de Software com IA Aplicada.” It is not one application with a single runtime; it is a collection of self-contained demos, templates, and reference implementations organized by teaching module.
At the highest level, the architecture splits into four kinds of content:
1. Curriculum and theory material
2. Standalone example projects
3. “Template” versions and “-z” variants of the same exercises
4. Supporting notes and infrastructure files
The README.md is the curriculum map. It ties each folder to a lesson topic and external references, but the executable architecture lives inside the subprojects.
Main repository boundaries
• modulo01-fundamentos-de-ia-e-llms-para-programadores
- Focuses on fundamentals: browser ML, recommendation systems, game AI, prompt patterns, MCP concepts, local models, OpenRouter, embeddings, and RAG.
• modulo02-integracao-apis-llms
- Focuses on API orchestration and agent-like workflows using OpenRouter, LangGraph, Neo4j, MCP-style integrations, and guardrails.
• lives
- Session notes and theoretical markdown material.
• embaixadores
- Mostly empty placeholder.
• windows
- Environment-specific notes, mainly around TensorFlow installation issues.
Architectural pattern across the repo
Most subprojects follow one of three patterns:
1. Browser-first AI demos
- UI in index.html plus client-side JavaScript/TypeScript.
- External AI or ML runtime accessed from the browser.
- Examples: temperature/top-k demo, multimodal demo, game AI, Next.js auth demo.
2. Node/TypeScript service with graph-based orchestration
- Server entrypoint in src/server.ts or src/index.ts.
- Business logic split into graph nodes, services, and prompt modules.
- External model provider accessed through a service wrapper, usually OpenRouter.
- Optional persistence in SQLite, Neo4j, or file-based stores.
- Examples: router gateway, appointment assistant, song highlights, prompt injection guardrails, Neo4j RAG.
3. Hybrid browser app with worker-based ML
- UI controls game/app state.
- Heavy ML or training/inference runs in Web Workers.
- Static assets, model files, and bundling infrastructure are included.
- Example: DuckHunt JS with TensorFlow-style model integration.
Module 01 architecture
Example 00 variants
• exemplo-00-template and exemplo-00-z
• Very small Node examples, likely used to demonstrate the simplest AI-related runtime structure.
• These act as starter and completed versions of the same lesson.
Example 01: e-commerce recommendation system
• exemplo-01-ecommerce-recomendations-template and multiple exemplo-01-ecommerce-recomendations-z/parte0X-* copies
• This is the clearest example of a layered app architecture in the repository.
• Main subsystems:
- src/controller
- User interaction and orchestration layer.
- Controllers coordinate view updates and service calls.
- src/service
- Domain/data logic for products and users.
- src/view
- Presentation layer for the browser UI.
- Includes reusable HTML templates like product cards and past purchase cards.
- src/workers
- Background model training, separated from the main UI thread.
- src/events
- Shared event constants and event bus definitions.
- data
- Static JSON datasets for users and products.
• Data flow:
- Browser UI loads initial HTML/CSS.
- Controllers request user and product data from services.
- Services read from local JSON files.
- Events notify views/controllers of state changes.
- Model training is offloaded to the worker, which isolates compute-heavy work from the UI.
• Architectural boundary:
- Presentation, domain/data access, and training are intentionally separated.
- The worker boundary is important because it represents asynchronous ML processing apart from the main interaction loop.
Example 02: DuckHunt game AI
• exemplo-02-vencendo-qualquer-jogo/DuckHunt-JS-parte01, parte02, and _template
• This is a browser game with a strong split between game objects, rendering, assets, and ML-related execution.
• Main subsystems:
- src/modules
- Core game entities: Game, Duck, Dog, Hud, Stage, Sound, Aim, Character.
- src/libs
- Utilities and level creation helpers.
- src/data
- Level definitions.
- src/assets
- Images and audio for the game.
- machine-learning
- ML-side code for browser inference/training integration.
- dist
- Built distributable output.
• Infrastructure files such as webpack.config.js and infrastructure.tf indicate that the project is both bundle-driven and deployment-aware.
• Data flow:
- Game loop drives render/update cycles.
- Assets and levels are loaded into the scene.
- ML code influences game behavior or automates play.
• Boundary:
- Core game logic remains separate from the machine-learning layer and from generated build artifacts.
Examples 03–05: browser AI demos
• exemplo-03-webai01
• exemplo-04-webai02-temperature-and-topK
• exemplo-05-webai03-multimodal
• These are smaller browser-based demos centered on prompts, generation settings, and multimodal interaction.
• Example 05 is split into:
- controllers
- services
- views
• That structure suggests a miniature MVC-ish frontend, where controller logic delegates to AI service wrappers and view renderers.
• The key boundary here is between user input UI and AI service calls, typically through browser-side JavaScript.
Examples 06–09: MCP and adjacent automation demos
• exemplo-06-playwright-testes
• exemplo-07-playwright-navegacao
• exemplo-08-context7
• exemplo-09-grafana-mcp
• These are not app products; they are automation/tooling scenarios.
• Their architecture is mostly configuration + prompts + small demo code.
• Notable boundaries:
- LLM-driven generation of Playwright tests or navigation steps.
- Context/documentation retrieval workflows.
- Observability/telemetry integration in the Grafana example.
• exemplo-09-grafana-mcp/alumnus is the richest system here:
- src/app.ts, src/index.ts
- src/database
- src/monitoring/otel.ts
- src/scenarios
- infra
- test
• This forms a complete service plus observability stack:
- app runtime emits telemetry
- OpenTelemetry collector forwards signals
- Prometheus, Loki, Tempo, and Grafana provide metrics, logs, traces, dashboards, and alerts
• The architectural boundary is between the business scenario code and the monitoring backend.
Examples 10–11: model-provider integration
• exemplo-10-ollama
• exemplo-11-openrouter
• These are lightweight integration demos.
• They show how a client or script talks to a local model runtime or a model-router API.
• The main boundary is external model inference:
- local Ollama for open-source models
- OpenRouter as a provider-aggregation layer
Examples 12–13: embeddings and RAG
• exemplo-12-embeddings-neo4j-template and exemplo-12-embeddings-neo4j
• exemplo-13-embeddings-neo4j-rag
• These are TypeScript applications centered on document processing and graph-backed semantic retrieval.
• Main subsystems:
- src/documentProcessor.ts
- Ingests and prepares documents.
- src/config.ts
- Runtime configuration.
- src/util.ts
- Shared helpers.
- src/index.ts
- Entry point.
- In the RAG variant:
- src/ai.ts
- likely handles model calls and answer generation
• External dependencies:
- Neo4j for graph storage / retrieval
- OpenRouter or another LLM endpoint for answer generation
• Data flow:
- Source document enters processor
- Text is chunked/normalized
- Embeddings or graph structures are stored in Neo4j
- Query time retrieves relevant context
- LLM generates a final response using retrieved context
• Boundary:
- Indexing pipeline vs question-answering pipeline is the main conceptual split.
Module 02 architecture
This module contains richer service-oriented systems with explicit orchestration graphs. The repeating structural pattern is:
• src/index.ts
- process bootstrap
• src/server.ts
- HTTP or service entrypoint
• src/config.ts
- environment and runtime config
• src/services
- integrations to LLM providers, databases, or domain backends
• src/graph
- LangGraph-style workflow definition
• src/graph/nodes
- individual step functions
• src/prompts
- prompt templates or prompt versioning
• tests
- end-to-end validation
• .env.example
- externalized configuration contract
• langgraph.json
- graph/runtime metadata for the orchestration layer
01. Smart model router gateway
• 01-smart-model-router-gateway
• A routing service that chooses or forwards to the appropriate model provider, centered on OpenRouter.
• Main boundary:
- request coming into the gateway
- model selection/routing logic
- outbound call to OpenRouter
• The test folder indicates the service is expected to behave as a gateway rather than a standalone UI.
02. LangChain intro
• 02-langchain-intro
• Demonstrates a graph of nodes such as intent identification, case transformation, fallback, and chat response.
• This is a controlled workflow graph rather than a free-form agent.
• Data flow:
- input arrives
- graph determines intent
- one of several nodes transforms or handles the request
- chat response or fallback is produced
• Architectural emphasis:
- decision nodes versus response nodes
- graph factory and graph definition separate from node logic
03. Medical appointment assistant
• 03-medical-appointment-template and 03-medical-appointment-z
• Combines a graph workflow with a domain service for appointments.
• Main node roles:
- identify intent
- scheduler
- canceller
- message generator
• Supporting layers:
- services/appointmentService.ts
- prompt templates for intent detection and message generation
• Data flow:
- user message enters
- intent is identified
- graph routes to scheduling or cancellation
- service layer performs appointment-side logic
- generated message is returned to user
• Boundary:
- conversational interpretation vs domain appointment actions
04. Song highlights assistant
• 04-song-highlights-template and 04-song-highlights-z
• A conversational system with memory/preferences and summarization.
• Main nodes:
- chat node
- save preferences node
- summarization node
- edge conditions
• Supporting services:
- OpenRouter service for model access
- preferences service
- in the -z variant, a memory service and local preferences.db
• Data flow:
- user chat is processed
- preferences are captured and persisted
- conversation may be summarized for context compression
- LLM produces responses based on stored memory/preferences
• Boundary:
- ephemeral chat context vs durable preference memory
05. Prompt injection safeguard
• 05-safeguard-prompt-injection-template and 05-safeguard-prompt-injection-z
• A guarded AI assistant with explicit policy enforcement.
• Main pieces:
- guardrailsCheckNode
- blockedNode
- chatNode
- state.ts
- prompt files for system, guardrails, blocked behavior, and user tasks
• Supporting services:
- openrouterService.ts
- in the -z variant, mcpService.ts
• Data flow:
- user request enters graph
- guardrail node evaluates intent/safety
- unsafe or policy-violating requests are routed to blocked behavior
- safe requests continue to chat generation
• Boundary:
- policy enforcement before model execution
- this is a clear “security gate” architecture
06. RAG on Neo4j for students
• 06-rag-neo4j-students-template and 06-rag-neo4j-students-z
• This is the most complete retrieval-augmented system in the repo.
• Main subsystems:
- data/seed.ts, seedHelpers.ts, courses.json
- data seeding and domain data preparation
- src/services/neo4jService.ts
- graph database access
- src/services/openrouterService.ts
- LLM access
- src/graph/nodes
- extractQuestionNode
- queryPlannerNode
- cypherGeneratorNode
- cypherExecutorNode
- cypherCorrectionNode
- analyticalResponseNode
- prompt files for query analysis, sales context, cypher generation/correction, NLP response, analytical response
• Data flow:
- user question arrives
- question extraction and planning determine the right query strategy
- graph generates Cypher
- Cypher runs against Neo4j
- if needed, query is corrected and retried
- final answer is composed with LLM support
• Boundary:
- natural-language interpretation vs graph query generation/execution
- query execution vs answer synthesis
• This is a textbook example of a multi-stage AI workflow with database-backed reasoning.
Cross-cutting infrastructure and tooling
Several technologies materially shape the architecture:
• Node.js / TypeScript
- used heavily in the API integration and RAG examples
• Plain JavaScript in the browser
- used for game and frontend demos
• Worker threads / Web Workers
- used when ML or training must be isolated from the UI thread
• TensorFlow.js / browser ML
- especially in the recommendation and game examples
• OpenRouter
- external LLM aggregation endpoint across multiple examples
• Neo4j
- graph-backed retrieval and query execution
• SQLite / local DB files
- lightweight persistence in some demos
• Docker Compose
- used where the example needs local infrastructure
• Terraform
- present in the DuckHunt examples and the observability stack
• LangGraph metadata
- indicates explicit graph-based orchestration in many modulo02 projects
• Prompt files
- prompts are first-class artifacts, not inline strings, in most AI-service examples
How to draw the architecture diagram
A good diagram of this repository should show:
• A top-level “course repository” container with four content areas:
- module 01 examples
- module 02 examples
- theory/live notes
- environment docs
• Inside module 01:
- separate boxes for each demo family, not one shared runtime
- browser UI, worker, and model/runtime boundaries for the recommendation and game examples
- prompt/model-provider demos as lightweight client-side apps
- embeddings/RAG examples with document ingestion and Neo4j
• Inside module 02:
- a repeated pattern of service entrypoint → graph orchestration → service integrations → external AI/database providers
- prompt files and graph nodes as distinct layers
- a security/guardrails branch in the prompt-injection example
- an observability backend stack in the Grafana scenario
• External services should be shown as separate systems:
- OpenRouter
- Ollama
- Neo4j
- Grafana/Prometheus/Loki/Tempo
- browser ML runtimes / TensorFlow.js
• Data stores should be separated by locality:
- local JSON files
- SQLite
- Neo4j
- observability storage backends
• Generated/build artifacts should be distinguished from source:
- dist
- bundled JS
- model files
The most important architectural takeaway is that this repo is a teaching corpus of several independent AI system patterns, not a single product. Each subproject demonstrates one boundary: UI vs worker, graph vs service, prompt vs policy gate, document ingestion vs retrieval, or local runtime vs external model provider.
Main entry points: README.md Course repo · graph/graph.ts Guardrails · graph/graph.ts Student RAG · server.ts Model router
Components 19
Repository
Course monorepo map and shared notes
- Course repo · Curriculum-oriented collection of independent teaching projects
README.md
Module 01
Foundations, browser demos, workers, and retrieval examples
- E-commerce recs · MVC-style recommendation demo with event bus and worker-based model training
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-01-ecommerce-recomendations-template/src/index.js - DuckHunt AI · Game loop, assets, level data, and worker-driven ML integration
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-02-vencendo-qualquer-jogo/DuckHunt-JS-parte01/src/modules/Game.js - Web AI demos · Small client-side experiments for prompts, temperature, top-k, and multimodal flows
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-05-webai03-multimodal/index.js - MCP/tooling · Playwright and context demos driven by prompts and MCP-style configuration
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-06-playwright-testes/example.mcp.json - Embeddings RAG · Document processing and Neo4j-backed retrieval/answering examples
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-13-embeddings-neo4j-rag/src/index.ts
Module 02
LLM API integration, workflow graphs, guardrails, and RAG
- Model router · Service that routes requests through OpenRouter
modulo02-integracao-apis-llms/01-smart-model-router-gateway/src/server.ts - Graph intro · Minimal LangGraph example with intent, transform, fallback, and chat nodes
modulo02-integracao-apis-llms/02-langchain-intro/src/graph/graph.ts - Appointments · Intent routing plus scheduler/canceller service actions
modulo02-integracao-apis-llms/03-medical-appointment-template/src/graph/graph.ts - Song highlights · Chat, preference persistence, and summarization workflow
modulo02-integracao-apis-llms/04-song-highlights-template/src/graph/graph.ts - Guardrails · Prompt-injection defense with guardrails, blocked, and chat branches
modulo02-integracao-apis-llms/05-safeguard-prompt-injection-template/src/graph/graph.ts - Student RAG · Multi-stage question analysis, Cypher generation, execution, correction, and answer synthesis
modulo02-integracao-apis-llms/06-rag-neo4j-students-template/src/graph/graph.ts - Observability demo · App runtime plus OpenTelemetry, dashboards, alerts, and infra for Grafana-style monitoring
modulo01-fundamentos-de-ia-e-llms-para-programadores/exemplo-09-grafana-mcp/alumnus/_alumnus/src/index.ts
Notes
Theory material and environment notes
- Session notes · Markdown-based lesson notes and conceptual material
lives/2026-02-24/README.md - Windows notes · Environment-specific installation guidance and caveats
windows/tensorflow.md
External Systems
Provider, database, and observability backends
- OpenRouter · External LLM aggregation and routing endpoint
- Neo4j · Graph storage and retrieval backend used by RAG examples
- Browser ML · In-browser ML runtime used by demos and games
- Observability stack · Prometheus, Loki, Tempo, Grafana, and OpenTelemetry backends
Connections 25
- Course repo → E-commerce recs: contains · Module 01 example project
- Course repo → DuckHunt AI: contains · Module 01 game example
- Course repo → Web AI demos: contains · Module 01 browser demos
- Course repo → MCP/tooling: contains · Module 01 tooling demos
- Course repo → Embeddings RAG: contains · Module 01 retrieval example
- Course repo → Model router: contains · Module 02 gateway example
- Course repo → Graph intro: contains · Module 02 graph example
- Course repo → Appointments: contains · Module 02 assistant example
- Course repo → Song highlights: contains · Module 02 memory assistant
- Course repo → Guardrails: contains · Module 02 safety assistant
- Course repo → Student RAG: contains · Module 02 RAG example
- Course repo → Observability demo: contains · Module 01 observability scenario
- Course repo → Session notes: contains · Session notes
- Course repo → Windows notes: contains · Environment notes
- E-commerce recs → Browser ML: runs in · Model training is isolated from the UI thread
- DuckHunt AI → Browser ML: uses · Browser-based ML inference/training runtime
- Embeddings RAG → Neo4j: stores in · Embeddings or graph context persisted to Neo4j
- Model router → OpenRouter: calls · Gateway forwards model requests to OpenRouter
- Appointments → OpenRouter: calls · Intent and message generation use an LLM provider
- Song highlights → OpenRouter: calls · Chat and summarization use OpenRouter
- Guardrails → OpenRouter: calls · Safe path reaches the model provider
- Guardrails → Model router: gates · Policy check precedes chat generation
- Student RAG → Neo4j: queries · Cypher execution and correction against graph data
- Student RAG → OpenRouter: calls · Question analysis and answer synthesis
- Observability demo → Observability stack: exports to · Telemetry flows into dashboards and backends