Arquitetura — studyAI

Visão geral da arquitetura do sistema: camadas, componentes e responsabilidades.

---

Índice

1. Visão geral
2. Camadas
3. Componentes
4. Diagrama de alto nível
5. Fluxo de dados
6. Observabilidade
7. Decisões arquiteturais

---

Visão geral

O studyAI é uma aplicação web com frontend e backend separados:

• Frontend (Next.js): Interface do utilizador, autenticação, gestão de projetos, chat
• Backend (FastAPI): API REST, lógica de negócio, orquestração de agentes, RAG
• Infraestrutura: PostgreSQL, Vector DB, Object Storage, Redis

A orquestração de agentes (LangGraph) corre no backend. O RAG usa os ficheiros e documentos do projeto como base de conhecimento.

---

Camadas

A carregar diagrama…

---

Componentes

Frontend (Next.js)

Backend (FastAPI)

Infraestrutura

---

Diagrama de alto nível

┌─────────────────────────────────────────────────────────────────────────────┐
│                              UTILIZADOR                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         FRONTEND (Next.js)                                  │
│  ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌──────┐ ┌─────────────┐          │
│  │  Auth   │ │ Projects │ │  Upload   │ │ Chat │ │  Questions   │          │
│  └─────────┘ └──────────┘ └───────────┘ └──────┘ └─────────────┘          │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │ HTTPS
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         API (FastAPI)                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  Middleware: Auth · Rate Limit · CORS · Logging                     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│  ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌─────────────┐        │
│  │ /auth   │ │/projects │ │  /files   │ │  /chat   │ │ /evaluate   │        │
│  └─────────┘ └──────────┘ └───────────┘ └──────────┘ └─────────────┘        │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                   ▼                   ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│   Ingest Pipeline     │ │   LangGraph Agents     │ │   RAG Service         │
│   Parse → Chunk →     │ │   Router → Planner →   │ │   Retrieve → Context  │
│   Embed → Index       │ │   Writer → ...         │ │   → LLM               │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
                    │                   │                   │
                    └───────────────────┼───────────────────┘
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         DATA LAYER                                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ PostgreSQL  │ │ Vector DB   │ │   Storage   │ │    Redis    │            │
│  │ (relacional)│ │ (embeddings)│ │  (ficheiros)│ │ (cache, q)  │            │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         OBSERVABILIDADE                                      │
│  LangSmith / Langfuse — Tracing LLM, agents, RAG · Métricas · Logs            │
└─────────────────────────────────────────────────────────────────────────────┘

---

Fluxo de dados

1. Upload e ingestão

User uploads PDF
    → API recebe ficheiro
    → Guarda em Object Storage
    → Regista em DB (status: pending)
    → Job: Parse PDF → texto
    → Chunk texto (por parágrafo/header)
    → Embed cada chunk
    → Guarda em Vector DB (metadata: project_id, file_id)
    → Atualiza DB (status: processed)

2. Geração de conteúdo

User: "Quero estudar X"
    → API /chat ou /generate
    → Router: intent = generate_content
    → Content Planner: RAG retrieval → estrutura
    → Content Writer: por cada secção, RAG → Markdown
    → Question Generator: documento → perguntas
    → Guarda documento + perguntas em DB
    → Re-indexa documento no Vector DB
    → Resposta ao user

3. Chat (QA)

User: "O que é Y?"
    → API /chat
    → Router: intent = qa
    → RAG QA Agent: embed query → retrieval → top-k chunks
    → LLM: chunks + query → resposta
    → Resposta ao user (streaming)

4. Avaliação

User submete resposta à pergunta
    → API /evaluate
    → Router: intent = evaluate
    → Question Evaluator: user_answer + solution + material
    → LLM: compara, score, feedback
    → Guarda em UserProgress
    → Resposta ao user

---

Observabilidade

O estudoAI depende fortemente de chamadas LLM e de fluxos multi-agente. A observabilidade é essencial para debug, otimização de custos e monitorização de qualidade.

Opções

Recomendação: LangSmith

LangSmith é a plataforma de observabilidade da LangChain. Integra nativamente com LangChain e LangGraph:

• Traces: Cada invocação de chain/agent gera um trace com spans (LLM calls, tool calls, retrieval)
• Token usage: Tokens de input/output por chamada, custo estimado
• Datasets: Guardar inputs/outputs para avaliação e regressão
• Evaluations: Correr evals em datasets (ex: groundedness, relevância)
• Debug: Inspecionar prompts, respostas e estado entre nós do grafo

Configuração: Definir LANGCHAIN_TRACING_V2=true e LANGCHAIN_API_KEY (ou LANGCHAIN_PROJECT). O tracing é automático para LangChain/LangGraph.

O que observar

Diagrama

API / Agents / RAG
        │
        │ (traces, spans)
        ▼
┌───────────────────┐
│    LangSmith      │
│  (ou Langfuse)    │
│                   │
│  • Traces         │
│  • Token usage    │
│  • Datasets       │
│  • Evaluations    │
└───────────────────┘

---

Decisões arquiteturais

Ver TECH_DECISIONS.md para decisões tecnológicas detalhadas.