new flashcards

AGENTS.md

@@ -0,0 +1,15 @@
+# Agents
+
+Have a read in `project-context.md` file, it will be the main source of truth for the project. Always keep it up to date with the latest project specs and architecture decisions.
+
+## UI specs
+- All UI needs to be have a glassy-look, with a not-so-dark background
+- Buttons needs to appear iOS-like and modern
+- All text inputs, displays and content should appear with a modern typefont
+- All texts needs to be in Brazilian Portuguese
+
+## Testing
+Follow strictly the testing requirements:
+- It should NOT have any form of integration testing, nor unit testing, or any kind of testing.
+- The only type of testing that should be done is building the project - make sure it compiles, and it's enough.
+- Don't create random tests or any kind of files that is related to testing. All testing will be done by a human later on.

Mindforge.API/Controllers/FlashcardController.cs

@@ -1,5 +1,3 @@
-using System;
-using System.Threading.Tasks;
 using Microsoft.AspNetCore.Mvc;
 using Mindforge.API.Exceptions;
 using Mindforge.API.Models.Requests;
@@ -21,23 +19,41 @@ namespace Mindforge.API.Controllers
         [HttpPost("generate")]
         public async Task<IActionResult> Generate([FromBody] FlashcardGenerateRequest request)
         {
-            if (string.IsNullOrWhiteSpace(request.FileContent) || request.Amount <= 0)
+            request ??= new FlashcardGenerateRequest();
+            if (request.FilePaths is null || request.FilePaths.Count == 0)
             {
-                throw new UserException("FileContent is required and Amount must be greater than 0.");
+                throw new UserException("Selecione ao menos um arquivo para gerar flashcards.");
             }
 
-            try
+            var libraries = await _flashcardService.GenerateFlashcardsAsync(request);
-            {
+            return Ok(new { libraries });
-                var base64Bytes = Convert.FromBase64String(request.FileContent);
-                request.FileContent = System.Text.Encoding.UTF8.GetString(base64Bytes);
-            }
-            catch (FormatException)
-            {
-                throw new UserException("FileContent must be a valid base64 string.");
         }
 
-            var response = await _flashcardService.GenerateFlashcardsAsync(request);
+        [HttpGet("libraries")]
-            return Ok(new { result = response });
+        public async Task<IActionResult> GetLibraries()
+        {
+            var libraries = await _flashcardService.GetLibrariesAsync();
+            return Ok(libraries);
+        }
+
+        [HttpGet("libraries/{id:long}")]
+        public async Task<IActionResult> GetLibraryById([FromRoute] long id)
+        {
+            var library = await _flashcardService.GetLibraryByIdAsync(id);
+            if (library is null)
+            {
+                return NotFound(new { error = "Biblioteca de flashcards nao encontrada." });
+            }
+
+            return Ok(library);
+        }
+
+        [HttpPost("review-session")]
+        public async Task<IActionResult> BuildReviewSession([FromBody] FlashcardReviewSessionRequest request)
+        {
+            request ??= new FlashcardReviewSessionRequest();
+            var cards = await _flashcardService.BuildReviewSessionAsync(request);
+            return Ok(new { cards });
         }
     }
 }

Mindforge.API/Mindforge.API.csproj

@@ -7,7 +7,9 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Dapper" Version="2.1.66" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.12" />
+    <PackageReference Include="Npgsql" Version="9.0.4" />
   </ItemGroup>
 
 </Project>

Mindforge.API/Models/Flashcards/FlashcardDraftCard.cs

@@ -0,0 +1,9 @@
+namespace Mindforge.API.Models.Flashcards
+{
+    public class FlashcardDraftCard
+    {
+        public string Front { get; set; } = string.Empty;
+        public string Back { get; set; } = string.Empty;
+        public int Position { get; set; }
+    }
+}

Mindforge.API/Models/Flashcards/FlashcardModels.cs

@@ -0,0 +1,29 @@
+namespace Mindforge.API.Models.Flashcards
+{
+    public class FlashcardLibrarySummary
+    {
+        public long Id { get; set; }
+        public string FilePath { get; set; } = string.Empty;
+        public string FileName { get; set; } = string.Empty;
+        public string Subject { get; set; } = string.Empty;
+        public string Difficulty { get; set; } = string.Empty;
+        public int CardCount { get; set; }
+        public DateTime CreatedAt { get; set; }
+        public DateTime UpdatedAt { get; set; }
+    }
+
+    public class FlashcardCard
+    {
+        public long Id { get; set; }
+        public long LibraryId { get; set; }
+        public string Front { get; set; } = string.Empty;
+        public string Back { get; set; } = string.Empty;
+        public int Position { get; set; }
+        public DateTime CreatedAt { get; set; }
+    }
+
+    public class FlashcardLibraryDetails : FlashcardLibrarySummary
+    {
+        public List<FlashcardCard> Cards { get; set; } = [];
+    }
+}

Mindforge.API/Models/Requests/FlashcardGenerateRequest.cs

@@ -4,18 +4,15 @@ namespace Mindforge.API.Models.Requests
 {
     public class FlashcardGenerateRequest
     {
-        public string FileContent { get; set; } = string.Empty;
+        public List<string> FilePaths { get; set; } = [];
-        public string FileName { get; set; } = string.Empty;
         public int Amount { get; set; }
         [JsonConverter(typeof(JsonStringEnumConverter))]
-        public FlashcardMode? Mode { get; set; } = FlashcardMode.Simple;
+        public FlashcardDifficulty Difficulty { get; set; } = FlashcardDifficulty.Easy;
     }
 
-    public enum FlashcardMode
+    public enum FlashcardDifficulty
     {
-        Basic,
+        Easy,
-        Simple,
+        Hard
-        Detailed,
-        Hyper
     }
 }

Mindforge.API/Models/Requests/FlashcardReviewSessionRequest.cs

@@ -0,0 +1,7 @@
+namespace Mindforge.API.Models.Requests
+{
+    public class FlashcardReviewSessionRequest
+    {
+        public List<long> LibraryIds { get; set; } = [];
+    }
+}

Mindforge.API/Program.cs

@@ -2,6 +2,7 @@ using Microsoft.AspNetCore.Builder;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Mindforge.API.Providers;
+using Mindforge.API.Repositories;
 using Mindforge.API.Services;
 using Mindforge.API.Services.Interfaces;
 
@@ -39,10 +40,25 @@ builder.Services.AddScoped<ILlmApiProvider, OpenAIApiProvider>();
 builder.Services.AddScoped<IAgentService, AgentService>();
 builder.Services.AddScoped<IFileService, FileService>();
 builder.Services.AddScoped<IFlashcardService, FlashcardService>();
+builder.Services.AddScoped<IFlashcardRepository, FlashcardRepository>();
 builder.Services.AddScoped<IGiteaService, GiteaService>();
 
 var app = builder.Build();
 
+using (var scope = app.Services.CreateScope())
+{
+    try
+    {
+        var flashcardRepository = scope.ServiceProvider.GetRequiredService<IFlashcardRepository>();
+        await flashcardRepository.EnsureSchemaAsync();
+        app.Logger.LogInformation("Flashcard schema checked successfully.");
+    }
+    catch (Exception ex)
+    {
+        app.Logger.LogError(ex, "Could not initialize flashcard schema on startup.");
+    }
+}
+
 app.UseCors("AllowAll");
 
 app.UseMiddleware<Mindforge.API.Middlewares.ExceptionHandlingMiddleware>();
@@ -80,4 +96,7 @@ if (string.IsNullOrEmpty(giteaRepoUrl))
 if (string.IsNullOrEmpty(giteaAccessToken))
     app.Logger.LogWarning("GITEA_ACCESS_TOKEN not found in configuration. Repository features will not work.");
 
+if (string.IsNullOrEmpty(builder.Configuration.GetConnectionString("MindforgeDb")))
+    app.Logger.LogWarning("MindforgeDb connection string not found. Falling back to default PostgreSQL connection.");
+
 app.Run();

Mindforge.API/Repositories/FlashcardRepository.cs

@@ -0,0 +1,260 @@
+using Dapper;
+using Mindforge.API.Models.Flashcards;
+using Mindforge.API.Services.Interfaces;
+using Npgsql;
+
+namespace Mindforge.API.Repositories
+{
+    public class FlashcardRepository : IFlashcardRepository
+    {
+        private const string DefaultConnectionString = "Host=iris.haven;Database=mindforge;Username=root;Password=root";
+        private readonly string _connectionString;
+
+        public FlashcardRepository(IConfiguration configuration)
+        {
+            _connectionString = configuration.GetConnectionString("MindforgeDb")
+                ?? configuration["MINDFORGE_DB_CONNECTION"]
+                ?? DefaultConnectionString;
+        }
+
+        public async Task EnsureSchemaAsync()
+        {
+            const string sql = """
+                CREATE TABLE IF NOT EXISTS flashcard_libraries (
+                    id BIGSERIAL PRIMARY KEY,
+                    file_path TEXT NOT NULL UNIQUE,
+                    file_name TEXT NOT NULL,
+                    subject TEXT NOT NULL,
+                    difficulty TEXT NOT NULL,
+                    card_count INTEGER NOT NULL,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                );
+
+                CREATE TABLE IF NOT EXISTS flashcards (
+                    id BIGSERIAL PRIMARY KEY,
+                    library_id BIGINT NOT NULL REFERENCES flashcard_libraries(id) ON DELETE CASCADE,
+                    front TEXT NOT NULL,
+                    back TEXT NOT NULL,
+                    position INTEGER NOT NULL,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                );
+
+                CREATE INDEX IF NOT EXISTS ix_flashcard_libraries_subject ON flashcard_libraries(subject);
+                CREATE INDEX IF NOT EXISTS ix_flashcards_library_id_position ON flashcards(library_id, position);
+                """;
+
+            await using var connection = CreateConnection();
+            await connection.OpenAsync();
+            await connection.ExecuteAsync(sql);
+        }
+
+        public async Task<FlashcardLibraryDetails> UpsertLibraryAsync(
+            string filePath,
+            string fileName,
+            string subject,
+            string difficulty,
+            IReadOnlyList<FlashcardDraftCard> cards)
+        {
+            await using var connection = CreateConnection();
+            await connection.OpenAsync();
+            await using var transaction = await connection.BeginTransactionAsync();
+
+            try
+            {
+                var existingId = await connection.ExecuteScalarAsync<long?>(
+                    "SELECT id FROM flashcard_libraries WHERE file_path = @FilePath FOR UPDATE;",
+                    new { FilePath = filePath },
+                    transaction);
+
+                long libraryId;
+                if (existingId.HasValue)
+                {
+                    libraryId = existingId.Value;
+                    await connection.ExecuteAsync(
+                        """
+                        UPDATE flashcard_libraries
+                        SET file_name = @FileName,
+                            subject = @Subject,
+                            difficulty = @Difficulty,
+                            card_count = @CardCount,
+                            updated_at = NOW()
+                        WHERE id = @LibraryId;
+                        """,
+                        new
+                        {
+                            FileName = fileName,
+                            Subject = subject,
+                            Difficulty = difficulty,
+                            CardCount = cards.Count,
+                            LibraryId = libraryId
+                        },
+                        transaction);
+
+                    await connection.ExecuteAsync(
+                        "DELETE FROM flashcards WHERE library_id = @LibraryId;",
+                        new { LibraryId = libraryId },
+                        transaction);
+                }
+                else
+                {
+                    libraryId = await connection.ExecuteScalarAsync<long>(
+                        """
+                        INSERT INTO flashcard_libraries (file_path, file_name, subject, difficulty, card_count)
+                        VALUES (@FilePath, @FileName, @Subject, @Difficulty, @CardCount)
+                        RETURNING id;
+                        """,
+                        new
+                        {
+                            FilePath = filePath,
+                            FileName = fileName,
+                            Subject = subject,
+                            Difficulty = difficulty,
+                            CardCount = cards.Count
+                        },
+                        transaction);
+                }
+
+                if (cards.Count > 0)
+                {
+                    await connection.ExecuteAsync(
+                        """
+                        INSERT INTO flashcards (library_id, front, back, position)
+                        VALUES (@LibraryId, @Front, @Back, @Position);
+                        """,
+                        cards.Select(card => new
+                        {
+                            LibraryId = libraryId,
+                            card.Front,
+                            card.Back,
+                            card.Position
+                        }),
+                        transaction);
+                }
+
+                await transaction.CommitAsync();
+                var details = await GetLibraryByIdAsync(libraryId);
+                if (details is null)
+                {
+                    throw new InvalidOperationException("Biblioteca gerada nao encontrada apos persistencia.");
+                }
+
+                return details;
+            }
+            catch
+            {
+                await transaction.RollbackAsync();
+                throw;
+            }
+        }
+
+        public async Task<IReadOnlyList<FlashcardLibrarySummary>> GetLibrariesAsync()
+        {
+            const string sql = """
+                SELECT
+                    id AS Id,
+                    file_path AS FilePath,
+                    file_name AS FileName,
+                    subject AS Subject,
+                    difficulty AS Difficulty,
+                    card_count AS CardCount,
+                    created_at AS CreatedAt,
+                    updated_at AS UpdatedAt
+                FROM flashcard_libraries
+                ORDER BY subject, file_name;
+                """;
+
+            await using var connection = CreateConnection();
+            await connection.OpenAsync();
+            var rows = await connection.QueryAsync<FlashcardLibrarySummary>(sql);
+            return rows.ToList();
+        }
+
+        public async Task<FlashcardLibraryDetails?> GetLibraryByIdAsync(long libraryId)
+        {
+            const string librarySql = """
+                SELECT
+                    id AS Id,
+                    file_path AS FilePath,
+                    file_name AS FileName,
+                    subject AS Subject,
+                    difficulty AS Difficulty,
+                    card_count AS CardCount,
+                    created_at AS CreatedAt,
+                    updated_at AS UpdatedAt
+                FROM flashcard_libraries
+                WHERE id = @LibraryId;
+                """;
+
+            const string cardsSql = """
+                SELECT
+                    id AS Id,
+                    library_id AS LibraryId,
+                    front AS Front,
+                    back AS Back,
+                    position AS Position,
+                    created_at AS CreatedAt
+                FROM flashcards
+                WHERE library_id = @LibraryId
+                ORDER BY position;
+                """;
+
+            await using var connection = CreateConnection();
+            await connection.OpenAsync();
+
+            var library = await connection.QuerySingleOrDefaultAsync<FlashcardLibrarySummary>(
+                librarySql,
+                new { LibraryId = libraryId });
+
+            if (library is null)
+            {
+                return null;
+            }
+
+            var cards = await connection.QueryAsync<FlashcardCard>(cardsSql, new { LibraryId = libraryId });
+            return new FlashcardLibraryDetails
+            {
+                Id = library.Id,
+                FilePath = library.FilePath,
+                FileName = library.FileName,
+                Subject = library.Subject,
+                Difficulty = library.Difficulty,
+                CardCount = library.CardCount,
+                CreatedAt = library.CreatedAt,
+                UpdatedAt = library.UpdatedAt,
+                Cards = cards.ToList()
+            };
+        }
+
+        public async Task<IReadOnlyList<FlashcardCard>> GetCardsForLibrariesAsync(IReadOnlyList<long> libraryIds)
+        {
+            if (libraryIds.Count == 0)
+            {
+                return [];
+            }
+
+            const string sql = """
+                SELECT
+                    id AS Id,
+                    library_id AS LibraryId,
+                    front AS Front,
+                    back AS Back,
+                    position AS Position,
+                    created_at AS CreatedAt
+                FROM flashcards
+                WHERE library_id = ANY(@LibraryIds)
+                ORDER BY library_id, position;
+                """;
+
+            await using var connection = CreateConnection();
+            await connection.OpenAsync();
+            var cards = await connection.QueryAsync<FlashcardCard>(sql, new { LibraryIds = libraryIds.ToArray() });
+            return cards.ToList();
+        }
+
+        private NpgsqlConnection CreateConnection()
+        {
+            return new NpgsqlConnection(_connectionString);
+        }
+    }
+}

Mindforge.API/Services/FlashcardService.cs

@@ -1,4 +1,6 @@
-using System.Threading.Tasks;
+using System.Text.Json;
+using Mindforge.API.Exceptions;
+using Mindforge.API.Models.Flashcards;
 using Mindforge.API.Models.Requests;
 using Mindforge.API.Services.Interfaces;
 
@@ -7,59 +9,234 @@ namespace Mindforge.API.Services
     public class FlashcardService : IFlashcardService
     {
         private readonly IAgentService _agentService;
+        private readonly IGiteaService _giteaService;
+        private readonly IFlashcardRepository _flashcardRepository;
         private readonly ILogger<FlashcardService> _logger;
+        private static readonly JsonSerializerOptions JsonOptions = new()
+        {
+            PropertyNameCaseInsensitive = true
+        };
 
-        public FlashcardService(IAgentService agentService, ILogger<FlashcardService> logger)
+        public FlashcardService(
+            IAgentService agentService,
+            IGiteaService giteaService,
+            IFlashcardRepository flashcardRepository,
+            ILogger<FlashcardService> logger)
         {
             _agentService = agentService;
+            _giteaService = giteaService;
+            _flashcardRepository = flashcardRepository;
             _logger = logger;
         }
 
-        public async Task<string> GenerateFlashcardsAsync(FlashcardGenerateRequest request)
+        public async Task<IReadOnlyList<FlashcardLibraryDetails>> GenerateFlashcardsAsync(FlashcardGenerateRequest request)
         {
-            var extraPrompt = request.Mode switch
+            if (request.FilePaths.Count == 0)
             {
-                FlashcardMode.Detailed => "Crie flashcards mais detalhados.",
+                throw new UserException("Selecione ao menos um arquivo para gerar flashcards.");
-                FlashcardMode.Hyper => "Adicione também pequenas questões para fixação, para que o usuário possa testar seus conhecimentos. As questões devem ser curtas e objetivas, como se fosse cobradas em prova mesmo.",
+            }
-                _ => ""
+
+            if (request.Amount is < 10 or > 30)
+            {
+                throw new UserException("A quantidade de flashcards deve estar entre 10 e 30 por arquivo.");
+            }
+
+            var uniqueFilePaths = request.FilePaths
+                .Where(path => !string.IsNullOrWhiteSpace(path))
+                .Select(path => path.Trim())
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList();
+
+            if (uniqueFilePaths.Count == 0)
+            {
+                throw new UserException("Nenhum caminho de arquivo valido foi enviado.");
+            }
+
+            var generatedLibraries = new List<FlashcardLibraryDetails>();
+            foreach (var filePath in uniqueFilePaths)
+            {
+                var fileContent = await _giteaService.GetFileContentAsync(filePath);
+                var fileName = Path.GetFileName(filePath);
+                var subject = ExtractSubject(filePath);
+                var cards = await GenerateCardsForFileAsync(filePath, fileContent, request.Amount, request.Difficulty);
+
+                var library = await _flashcardRepository.UpsertLibraryAsync(
+                    filePath,
+                    fileName,
+                    subject,
+                    request.Difficulty.ToString(),
+                    cards);
+
+                generatedLibraries.Add(library);
+            }
+
+            return generatedLibraries;
+        }
+
+        public Task<IReadOnlyList<FlashcardLibrarySummary>> GetLibrariesAsync()
+        {
+            return _flashcardRepository.GetLibrariesAsync();
+        }
+
+        public Task<FlashcardLibraryDetails?> GetLibraryByIdAsync(long libraryId)
+        {
+            return _flashcardRepository.GetLibraryByIdAsync(libraryId);
+        }
+
+        public async Task<IReadOnlyList<FlashcardCard>> BuildReviewSessionAsync(FlashcardReviewSessionRequest request)
+        {
+            var libraryIds = (request.LibraryIds ?? [])
+                .Where(id => id > 0)
+                .Distinct()
+                .ToList();
+
+            if (libraryIds.Count == 0)
+            {
+                throw new UserException("Selecione ao menos uma biblioteca para iniciar a revisao.");
+            }
+
+            return await _flashcardRepository.GetCardsForLibrariesAsync(libraryIds);
+        }
+
+        private async Task<IReadOnlyList<FlashcardDraftCard>> GenerateCardsForFileAsync(
+            string filePath,
+            string fileContent,
+            int amount,
+            FlashcardDifficulty difficulty)
+        {
+            var difficultyInstruction = difficulty switch
+            {
+                FlashcardDifficulty.Hard => "Crie perguntas mais desafiadoras, focando diferencas finas e cobrancas de prova.",
+                _ => "Crie perguntas diretas e objetivas para facilitar memorizacao inicial."
             };
 
-            string systemPrompt = $@"Você é um assistente educacional especializado em criar flashcards para o Anki.
+            var systemPrompt =
-Baseado no texto fornecido, crie exatamente {request.Amount} flashcards que focam nos conceitos mais importantes e difíceis.
+                "Voce e um assistente educacional especializado em flashcards.\n"
-A resposta FINAL deve ser APENAS no formato CSV, pronto para importação no Anki, sem nenhum texto adicional antes ou depois.
+                + $"Gere exatamente {amount} flashcards em Portugues do Brasil.\n"
-O formato CSV deve ter duas colunas: a frente da carta (pergunta/conceito) e o verso (resposta/explicação). Use ponto e vírgula (;) como separador. Não adicione o cabeçalho.
+                + "Cada item precisa conter:\n"
-As perguntas e respostas devem estar estritamente em Português do Brasil.
+                + "- front: pergunta ou gatilho curto\n"
+                + "- back: resposta clara, correta e objetiva\n"
+                + $"{difficultyInstruction}\n"
+                + "Responda apenas com JSON valido, sem markdown, no formato:\n"
+                + "{\n"
+                + "  \"flashcards\": [\n"
+                + "    { \"front\": \"texto\", \"back\": \"texto\" }\n"
+                + "  ]\n"
+                + "}";
 
-Exemplo de saída:
+            var userPrompt = $"""
-""Qual é a capital do Brasil?"";""Brasília""
+                Arquivo: {filePath}
-""Qual é a maior cidade do Brasil?"";""São Paulo""
+                Conteudo:
+                {fileContent}
+                """;
 
-Com base no arquivo fornecido, crie exatamente {request.Amount} flashcards que focam nos conceitos mais importantes e difíceis.
+            var rawResult = await _agentService.ProcessRequestAsync(systemPrompt, userPrompt);
-{extraPrompt}
+            var cards = ParseFlashcardsFromJson(rawResult);
-";
 
-            string userPrompt = $"Arquivo: {request.FileName}\nConteúdo:\n{request.FileContent}";
+            if (cards.Count < amount)
-
-            var result = await _agentService.ProcessRequestAsync(systemPrompt, userPrompt);
-
-            var lines = result.Split('\n');
-
-            if (lines.Length == 0)
             {
-                throw new Exception("Nenhum flashcard gerado.");
+                throw new Exception($"Quantidade insuficiente de flashcards gerados para {filePath}. Esperado: {amount}. Recebido: {cards.Count}.");
             }
 
-            if (lines.Length > request.Amount)
+            if (cards.Count > amount)
             {
-                _logger.LogWarning("Quantidade de flashcards excede o limite.");
+                _logger.LogWarning(
+                    "Quantidade de flashcards acima do solicitado para {FilePath}. Solicitado: {Amount}. Recebido: {Generated}.",
+                    filePath,
+                    amount,
+                    cards.Count);
+                cards = cards.Take(amount).ToList();
             }
 
-            if (lines.Length < request.Amount)
+            for (var i = 0; i < cards.Count; i++)
             {
-                _logger.LogWarning("Quantidade de flashcards abaixo do limite.");
+                cards[i].Position = i + 1;
             }
 
-            return result;
+            return cards;
+        }
+
+        private static List<FlashcardDraftCard> ParseFlashcardsFromJson(string rawResult)
+        {
+            var cleanJson = StripJsonCodeBlock(rawResult);
+
+            var payload = JsonSerializer.Deserialize<FlashcardJsonPayload>(cleanJson, JsonOptions);
+            if (payload?.Flashcards is { Count: > 0 })
+            {
+                return payload.Flashcards
+                    .Where(card => !string.IsNullOrWhiteSpace(card.Front) && !string.IsNullOrWhiteSpace(card.Back))
+                    .Select(card => new FlashcardDraftCard
+                    {
+                        Front = card.Front.Trim(),
+                        Back = card.Back.Trim()
+                    })
+                    .ToList();
+            }
+
+            var directList = JsonSerializer.Deserialize<List<FlashcardJsonCard>>(cleanJson, JsonOptions);
+            if (directList is { Count: > 0 })
+            {
+                return directList
+                    .Where(card => !string.IsNullOrWhiteSpace(card.Front) && !string.IsNullOrWhiteSpace(card.Back))
+                    .Select(card => new FlashcardDraftCard
+                    {
+                        Front = card.Front.Trim(),
+                        Back = card.Back.Trim()
+                    })
+                    .ToList();
+            }
+
+            throw new Exception("Resposta de flashcards invalida. O modelo nao retornou JSON estruturado.");
+        }
+
+        private static string StripJsonCodeBlock(string value)
+        {
+            var trimmed = value.Trim();
+            if (!trimmed.StartsWith("```", StringComparison.Ordinal))
+            {
+                return trimmed;
+            }
+
+            var lines = trimmed.Split('\n');
+            if (lines.Length <= 2)
+            {
+                return trimmed.Trim('`', '\r', '\n');
+            }
+
+            return string.Join('\n', lines.Skip(1).Take(lines.Length - 2)).Trim();
+        }
+
+        private static string ExtractSubject(string filePath)
+        {
+            var normalized = filePath.Replace('\\', '/');
+            var segments = normalized.Split('/', StringSplitOptions.RemoveEmptyEntries);
+            if (segments.Length == 0)
+            {
+                return "Geral";
+            }
+
+            var concursosIndex = Array.FindIndex(
+                segments,
+                segment => segment.Equals("concursos", StringComparison.OrdinalIgnoreCase)
+                    || segment.Equals("concurso", StringComparison.OrdinalIgnoreCase));
+
+            if (concursosIndex >= 0 && concursosIndex + 1 < segments.Length)
+            {
+                return segments[concursosIndex + 1];
+            }
+
+            return segments[0];
+        }
+
+        private class FlashcardJsonPayload
+        {
+            public List<FlashcardJsonCard> Flashcards { get; set; } = [];
+        }
+
+        private class FlashcardJsonCard
+        {
+            public string Front { get; set; } = string.Empty;
+            public string Back { get; set; } = string.Empty;
         }
     }
 }

Mindforge.API/Services/GiteaService.cs

@@ -10,10 +10,11 @@ namespace Mindforge.API.Services
     public class GiteaService : IGiteaService
     {
         private readonly HttpClient _httpClient;
-        private readonly string _baseUrl;
+        private readonly string _baseUrl = string.Empty;
-        private readonly string _owner;
+        private readonly string _owner = string.Empty;
-        private readonly string _repo;
+        private readonly string _repo = string.Empty;
-        private readonly string _token;
+        private readonly string _token = string.Empty;
+        private readonly bool _isConfigured;
 
         private static readonly JsonSerializerOptions JsonOptions = new()
         {
@@ -25,25 +26,35 @@ namespace Mindforge.API.Services
             _httpClient = httpClient;
 
             var repoUrl = configuration["GITEA_REPO_URL"];
-            if (string.IsNullOrEmpty(repoUrl))
+            var token = configuration["GITEA_ACCESS_TOKEN"];
-                throw new InvalidOperationException("GITEA_REPO_URL is not set in configuration.");
+            if (string.IsNullOrWhiteSpace(repoUrl) || string.IsNullOrWhiteSpace(token))
-
+            {
-            _token = configuration["GITEA_ACCESS_TOKEN"]
+                _isConfigured = false;
-                ?? throw new InvalidOperationException("GITEA_ACCESS_TOKEN is not set in configuration.");
+                return;
-
-            // Parse: https://host/owner/repo or https://host/owner/repo.git
-            var normalizedUrl = repoUrl.TrimEnd('/').TrimEnd(".git".ToCharArray());
-            var uri = new Uri(normalizedUrl);
-            _baseUrl = $"{uri.Scheme}://{uri.Host}{(uri.IsDefaultPort ? "" : $":{uri.Port}")}";
-            var parts = uri.AbsolutePath.Trim('/').Split('/');
-            _owner = parts[0];
-            _repo = parts[1];
             }
 
-        public string GetRepositoryName() => _repo;
+            var normalizedUrl = repoUrl.TrimEnd('/').TrimEnd(".git".ToCharArray());
+            var uri = new Uri(normalizedUrl);
+            var parts = uri.AbsolutePath.Trim('/').Split('/');
+            if (parts.Length < 2)
+            {
+                _isConfigured = false;
+                return;
+            }
+
+            _baseUrl = $"{uri.Scheme}://{uri.Host}{(uri.IsDefaultPort ? "" : $":{uri.Port}")}";
+            _owner = parts[0];
+            _repo = parts[1];
+            _token = token;
+            _isConfigured = true;
+        }
+
+        public string GetRepositoryName() => _isConfigured ? _repo : "repositorio";
 
         public async Task<List<FileTreeNode>> GetFileTreeAsync()
         {
+            EnsureConfigured();
+
             // Get the master branch to obtain the latest commit SHA
             var branchJson = await GetApiAsync($"/api/v1/repos/{_owner}/{_repo}/branches/master");
             var branch = JsonSerializer.Deserialize<GiteaBranch>(branchJson, JsonOptions)
@@ -61,6 +72,8 @@ namespace Mindforge.API.Services
 
         public async Task<string> GetFileContentAsync(string path)
         {
+            EnsureConfigured();
+
             var request = new HttpRequestMessage(HttpMethod.Get,
                 $"{_baseUrl}/api/v1/repos/{_owner}/{_repo}/raw/{path}?ref=master");
             request.Headers.Add("Authorization", $"token {_token}");
@@ -75,6 +88,8 @@ namespace Mindforge.API.Services
 
         private async Task<string> GetApiAsync(string endpoint)
         {
+            EnsureConfigured();
+
             var request = new HttpRequestMessage(HttpMethod.Get, $"{_baseUrl}{endpoint}");
             request.Headers.Add("Authorization", $"token {_token}");
             var response = await _httpClient.SendAsync(request);
@@ -82,6 +97,14 @@ namespace Mindforge.API.Services
             return await response.Content.ReadAsStringAsync();
         }
 
+        private void EnsureConfigured()
+        {
+            if (!_isConfigured)
+            {
+                throw new InvalidOperationException("Gitea nao configurado. Defina GITEA_REPO_URL e GITEA_ACCESS_TOKEN.");
+            }
+        }
+
         private static List<FileTreeNode> BuildTree(List<GiteaTreeItem> items)
         {
             var root = new List<FileTreeNode>();

Mindforge.API/Services/Interfaces/IFlashcardRepository.cs

@@ -0,0 +1,18 @@
+using Mindforge.API.Models.Flashcards;
+
+namespace Mindforge.API.Services.Interfaces
+{
+    public interface IFlashcardRepository
+    {
+        Task EnsureSchemaAsync();
+        Task<FlashcardLibraryDetails> UpsertLibraryAsync(
+            string filePath,
+            string fileName,
+            string subject,
+            string difficulty,
+            IReadOnlyList<FlashcardDraftCard> cards);
+        Task<IReadOnlyList<FlashcardLibrarySummary>> GetLibrariesAsync();
+        Task<FlashcardLibraryDetails?> GetLibraryByIdAsync(long libraryId);
+        Task<IReadOnlyList<FlashcardCard>> GetCardsForLibrariesAsync(IReadOnlyList<long> libraryIds);
+    }
+}

Mindforge.API/Services/Interfaces/IFlashcardService.cs

@@ -1,10 +1,13 @@
-using System.Threading.Tasks;
+using Mindforge.API.Models.Flashcards;
 using Mindforge.API.Models.Requests;
 
 namespace Mindforge.API.Services.Interfaces
 {
     public interface IFlashcardService
     {
-        Task<string> GenerateFlashcardsAsync(FlashcardGenerateRequest request);
+        Task<IReadOnlyList<FlashcardLibraryDetails>> GenerateFlashcardsAsync(FlashcardGenerateRequest request);
+        Task<IReadOnlyList<FlashcardLibrarySummary>> GetLibrariesAsync();
+        Task<FlashcardLibraryDetails?> GetLibraryByIdAsync(long libraryId);
+        Task<IReadOnlyList<FlashcardCard>> BuildReviewSessionAsync(FlashcardReviewSessionRequest request);
     }
 }

Mindforge.API/appsettings.json

@@ -6,6 +6,9 @@
     }
   },
   "AllowedHosts": "*",
+  "ConnectionStrings": {
+    "MindforgeDb": "Host=localhost;Port=3307;Database=mindforge;Username=root;Password=root"
+  },
   "OPENAI_API_URL": "https://openrouter.ai/api/v1",
   "OPENAI_TOKEN": "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",
   "OPENAI_MODEL": "openai/gpt-5.4-mini",

Mindforge.API/deploy/mindforge-api.yaml

@@ -39,6 +39,11 @@ spec:
                 secretKeyRef:
                   name: mindforge-secrets
                   key: GITEA_ACCESS_TOKEN
+            - name: ConnectionStrings__MindforgeDb
+              valueFrom:
+                secretKeyRef:
+                  name: mindforge-secrets
+                  key: ConnectionStrings__MindforgeDb
           resources:
             requests:
               memory: "128Mi"

Mindforge.Web/src/app.tsx

@@ -4,9 +4,10 @@ import { Header } from './components/Header';
 import { Sidebar } from './components/Sidebar';
 import { VerificadorComponent } from './components/VerificadorComponent';
 import { FlashcardComponent } from './components/FlashcardComponent';
+import { FlashcardReviewComponent } from './components/FlashcardReviewComponent';
 
 export function App() {
-  const [activeModule, setActiveModule] = useState<'home' | 'verificador' | 'flashcards'>('home');
+  const [activeModule, setActiveModule] = useState<'home' | 'verificador' | 'flashcards' | 'revisao-flashcards'>('home');
 
   return (
     <>
@@ -17,8 +18,8 @@ export function App() {
           <div style={{ display: activeModule === 'home' || !activeModule ? 'block' : 'none' }}>
             <div class="home-hero">
               <img src="/assets/mindforge-banner.png" alt="Mindforge Banner" style={{ maxWidth: '100%', height: 'auto', marginBottom: '2rem', borderRadius: '12px', boxShadow: '0 4px 15px rgba(0,0,0,0.5)', zIndex: -10 }} />
-              <h1 class="hero-title">Mindforge! - STAY HARD!</h1>
+              <h1 class="hero-title">Mindforge - Forja Mental</h1>
-              <p class="hero-subtitle">Sua ferramenta de forja mental e estudos.</p>
+              <p class="hero-subtitle">Sua ferramenta de estudos para concursos.</p>
             </div>
           </div>
           <div style={{ display: activeModule === 'verificador' ? 'block' : 'none', height: '100%', width: '100%' }}>
@@ -27,6 +28,9 @@ export function App() {
           <div style={{ display: activeModule === 'flashcards' ? 'block' : 'none', height: '100%', width: '100%' }}>
             <FlashcardComponent />
           </div>
+          <div style={{ display: activeModule === 'revisao-flashcards' ? 'block' : 'none', height: '100%', width: '100%' }}>
+            <FlashcardReviewComponent />
+          </div>
         </main>
       </div>
     </>

Mindforge.Web/src/components/FileTreeComponent.css

@@ -64,7 +64,7 @@
 }
 
 .tree-file-label input[type="checkbox"] {
-  accent-color: #7c6fcd;
+  accent-color: var(--color-accent);
   width: 14px;
   height: 14px;
   cursor: pointer;

Mindforge.Web/src/components/FlashcardComponent.css

@@ -1,6 +1,6 @@
 .flashcard-container {
   width: 100%;
-  max-width: 800px;
+  max-width: 900px;
   margin: 0 auto;
   animation: slideUp 0.5s ease-out;
   display: flex;
@@ -8,14 +8,21 @@
   gap: 1.5rem;
 }
 
+.flashcard-title {
+  font-size: 2.5rem;
+}
+
 .flashcard-form {
   display: flex;
   flex-direction: column;
   gap: 1.2rem;
-  background: rgba(255, 255, 255, 0.05);
+  background: rgba(255, 255, 255, 0.06);
   padding: 2rem;
   border-radius: 12px;
-  border: 1px solid rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  box-shadow: 0 14px 36px rgba(0, 0, 0, 0.2);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
 }
 
 .input-group {
@@ -30,47 +37,10 @@
   color: var(--color-text-creamy);
 }
 
-.text-area {
+.selection-meta {
-  width: 100%;
+  font-size: 0.85rem;
-  min-height: 200px;
+  color: rgba(255, 255, 255, 0.55);
-  background: rgba(0, 0, 0, 0.2);
+  margin-top: 0.4rem;
-  border: 1px solid rgba(255, 255, 255, 0.2);
-  border-radius: 8px;
-  padding: 1rem;
-  color: var(--color-text-creamy);
-  font-family: inherit;
-  font-size: 1rem;
-  resize: vertical;
-}
-
-.text-area:focus {
-  outline: none;
-  border-color: var(--color-accent);
-}
-
-.file-input-wrapper {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-}
-
-.file-input {
-  display: none;
-}
-
-.file-input-label {
-  background: var(--color-sidebar);
-  color: var(--color-text-creamy);
-  padding: 0.6rem 1.2rem;
-  border-radius: 6px;
-  cursor: pointer;
-  border: 1px solid rgba(255, 255, 255, 0.2);
-  transition: all 0.2s ease;
-}
-
-.file-input-label:hover {
-  background: rgba(255, 255, 255, 0.1);
-  border-color: var(--color-accent);
 }
 
 .slider-wrapper {
@@ -86,72 +56,42 @@
   width: 100%;
   height: 8px;
   background: rgba(0, 0, 0, 0.3);
-  border-radius: 4px;
+  border-radius: 999px;
   outline: none;
 }
 
 .slider-input::-webkit-slider-thumb {
   -webkit-appearance: none;
   appearance: none;
-  width: 20px;
+  width: 22px;
-  height: 20px;
+  height: 22px;
   border-radius: 50%;
-  background: var(--color-accent);
+  background: #f4f5f5;
+  border: 2px solid rgba(var(--color-accent-rgb), 0.9);
+  box-shadow: 0 6px 16px rgba(var(--color-accent-rgb), 0.35);
   cursor: pointer;
-  transition: transform 0.1s;
-}
-
-.slider-input::-webkit-slider-thumb:hover {
-  transform: scale(1.2);
 }
 
 .amount-display {
   font-weight: 700;
   color: var(--color-accent);
-  min-width: 40px;
+  min-width: 44px;
   text-align: right;
   font-size: 1.1rem;
 }
 
-/* Spinner */
+.flashcard-error {
-.spinner-container {
+  color: #ff9c96;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  padding: 3rem 0;
-  gap: 1rem;
-}
-
-.spinner {
-  width: 50px;
-  height: 50px;
-  border: 4px solid rgba(255, 255, 255, 0.1);
-  border-left-color: var(--color-accent);
-  border-radius: 50%;
-  animation: spin 1s linear infinite;
-}
-
-@keyframes spin {
-  0% { transform: rotate(0deg); }
-  100% { transform: rotate(360deg); }
-}
-
-.success-message {
-  color: #7ee787;
-  text-align: center;
-  font-weight: 700;
   margin-top: 1rem;
-  animation: fadeIn 0.5s ease-out;
 }
 
 .radio-group {
   display: flex;
   flex-wrap: wrap;
-  background: rgba(0, 0, 0, 0.3);
+  background: rgba(0, 0, 0, 0.28);
   padding: 4px;
   border-radius: 12px;
-  border: 1px solid rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.12);
   width: fit-content;
   overflow: hidden;
   gap: 4px;
@@ -159,8 +99,7 @@
 
 .radio-item {
   position: relative;
-  flex: 1;
+  min-width: 120px;
-  min-width: 100px;
 }
 
 .radio-item input[type="radio"] {
@@ -178,30 +117,104 @@
   cursor: pointer;
   border-radius: 8px;
   font-size: 0.95rem;
-  font-weight: 600;
+  font-weight: 700;
-  color: rgba(255, 255, 255, 0.6);
+  color: rgba(255, 255, 255, 0.65);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition: all 0.25s ease;
   white-space: nowrap;
 }
 
 .radio-item input[type="radio"]:checked + .radio-label {
   background: var(--color-accent);
-  color: #000;
+  color: #012f3b;
-  box-shadow: 0 4px 12px rgba(var(--color-accent-rgb), 0.3);
+  box-shadow: 0 4px 12px rgba(var(--color-accent-rgb), 0.35);
 }
 
-.radio-item:hover .radio-label:not(.radio-item input[type="radio"]:checked + .radio-label) {
+.radio-item:hover .radio-label {
-  background: rgba(255, 255, 255, 0.05);
+  color: rgba(255, 255, 255, 0.92);
-  color: #fff;
 }
 
-/* Animations for selection */
+.spinner-container {
-.radio-item input[type="radio"]:checked + .radio-label {
+  display: flex;
-  animation: selectBounce 0.3s ease-out;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem 0;
+  gap: 1rem;
 }
 
-@keyframes selectBounce {
+.spinner {
-  0% { transform: scale(0.95); }
+  width: 50px;
-  50% { transform: scale(1.02); }
+  height: 50px;
-  100% { transform: scale(1); }
+  border: 4px solid rgba(255, 255, 255, 0.12);
+  border-left-color: var(--color-accent);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+.flashcard-result-panel {
+  background: rgba(255, 255, 255, 0.06);
+  border-radius: 12px;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  padding: 1.5rem;
+  text-align: left;
+}
+
+.flashcard-result-panel h3 {
+  margin: 0 0 1rem 0;
+  font-size: 1.1rem;
+  color: rgba(255, 255, 255, 0.94);
+}
+
+.flashcard-result-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 0.85rem;
+}
+
+.flashcard-result-item {
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 10px;
+  padding: 0.85rem 1rem;
+}
+
+.flashcard-result-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+  font-size: 0.95rem;
+}
+
+.flashcard-result-header span {
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.flashcard-result-meta {
+  margin-top: 0.45rem;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.85rem;
+  font-size: 0.85rem;
+  color: rgba(255, 255, 255, 0.65);
+}
+
+@keyframes spin {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+@media (max-width: 720px) {
+  .flashcard-form {
+    padding: 1.2rem;
+  }
+
+  .flashcard-result-header {
+    flex-direction: column;
+    align-items: flex-start;
+  }
 }

Mindforge.Web/src/components/FlashcardComponent.tsx

@@ -1,181 +1,147 @@
 import { useState } from 'preact/hooks';
-import { MindforgeApiService, type FlashcardMode } from '../services/MindforgeApiService';
+import {
+  MindforgeApiService,
+  type FlashcardDifficulty,
+  type FlashcardLibraryDetails,
+} from '../services/MindforgeApiService';
 import { FileTreeComponent } from './FileTreeComponent';
 import { Button } from './Button';
 import './FlashcardComponent.css';
 
-// Mapping of flashcard mode to its maximum allowed amount
+const minAmount = 10;
-const modeMax: Record<FlashcardMode, number> = {
+const maxAmount = 30;
-  Basic: 25,
-  Simple: 30,
-  Detailed: 70,
-  Hyper: 130,
-};
 
-function utf8ToBase64(str: string): string {
+function difficultyLabel(difficulty: string) {
-  const bytes = new TextEncoder().encode(str);
+  return difficulty === 'Hard' ? 'Dificil' : 'Facil';
-  const binary = Array.from(bytes, byte => String.fromCharCode(byte)).join('');
-  return window.btoa(binary);
 }
 
 export function FlashcardComponent() {
   const [selectedPaths, setSelectedPaths] = useState<string[]>([]);
   const [amount, setAmount] = useState<number>(20);
-  const [mode, setMode] = useState<FlashcardMode>('Simple');
+  const [difficulty, setDifficulty] = useState<FlashcardDifficulty>('Easy');
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const [success, setSuccess] = useState<boolean>(false);
+  const [generatedLibraries, setGeneratedLibraries] = useState<FlashcardLibraryDetails[]>([]);
-
-  const handleModeChange = (newMode: FlashcardMode) => {
-    setMode(newMode);
-    setAmount(20);
-  };
 
   const handleGenerate = async () => {
     if (selectedPaths.length === 0) {
-      setError('Selecione pelo menos um arquivo do repositório para gerar os flashcards.');
+      setError('Selecione pelo menos um arquivo do repositorio para gerar os flashcards.');
       return;
     }
 
     setLoading(true);
     setError(null);
-    setSuccess(false);
 
     try {
-      // Fetch all selected files and merge their content
+      const response = await MindforgeApiService.generateFlashcards({
-      const fileContents = await Promise.all(
+        filePaths: selectedPaths,
-        selectedPaths.map(path => MindforgeApiService.getFileContent(path))
-      );
-
-      const mergedContent = fileContents.map(f => f.content).join('\n\n---\n\n');
-      const mergedFileName = selectedPaths.length === 1
-        ? (selectedPaths[0].split('/').pop() ?? 'merged.md')
-        : 'merged.md';
-
-      const base64Content = utf8ToBase64(mergedContent);
-      const res = await MindforgeApiService.generateFlashcards({
-        fileContent: base64Content,
-        fileName: mergedFileName,
         amount,
-        mode,
+        difficulty,
       });
 
-      downloadCSV(res.result);
+      setGeneratedLibraries(response.libraries);
-      setSuccess(true);
     } catch (err: any) {
-      setError(err.message || 'Ocorreu um erro ao gerar os flashcards.');
+      setError(err?.message || 'Ocorreu um erro ao gerar os flashcards.');
     } finally {
       setLoading(false);
     }
   };
 
-  const downloadCSV = (content: string) => {
-    const bom = new Uint8Array([0xEF, 0xBB, 0xBF]);
-    const blob = new Blob([bom, content], { type: 'text/csv;charset=utf-8;' });
-    const url = URL.createObjectURL(blob);
-    const link = document.createElement('a');
-    link.href = url;
-    link.setAttribute('download', `flashcards_${Date.now()}.csv`);
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
-    URL.revokeObjectURL(url);
-  };
-
   return (
     <div className="flashcard-container">
-      <h2 className="title" style={{ fontSize: '2.5rem' }}>Gerador de Flashcards</h2>
+      <h2 className="title flashcard-title">Gerador de Flashcards</h2>
-      <p className="subtitle">Selecione os arquivos do repositório para gerar flashcards. Múltiplos arquivos serão combinados.</p>
+      <p className="subtitle">Selecione os arquivos do repositorio para gerar bibliotecas de flashcards.</p>
 
       <div className="flashcard-form">
         <div className="input-group">
-          <label>Arquivos do Repositório</label>
+          <label>Arquivos do Repositorio</label>
           <FileTreeComponent selectedPaths={selectedPaths} onSelectionChange={setSelectedPaths} />
           {selectedPaths.length > 0 && (
-            <div style={{ fontSize: '0.85rem', color: 'rgba(255,255,255,0.5)', marginTop: '0.4rem' }}>
+            <div className="selection-meta">
-              {selectedPaths.length} arquivo{selectedPaths.length !== 1 ? 's' : ''} selecionado{selectedPaths.length !== 1 ? 's' : ''}
+              {selectedPaths.length} arquivo{selectedPaths.length !== 1 ? 's' : ''} selecionado
-              {selectedPaths.length > 1 ? ' — conteúdo será combinado' : ''}
+              {selectedPaths.length !== 1 ? 's' : ''}
             </div>
           )}
         </div>
 
         <div className="input-group">
-          <label>Quantidade Estimada de Flashcards (10 - {modeMax[mode]})</label>
+          <label>Quantidade por Arquivo ({minAmount} - {maxAmount})</label>
           <div className="slider-wrapper">
             <input
               type="range"
               className="slider-input"
-              min="10"
+              min={minAmount}
-              max={modeMax[mode]}
+              max={maxAmount}
               value={amount}
-              onInput={(e) => setAmount(parseInt((e.target as HTMLInputElement).value))}
+              onInput={(e) => setAmount(parseInt((e.target as HTMLInputElement).value, 10))}
             />
             <span className="amount-display">{amount}</span>
           </div>
         </div>
 
         <div className="input-group">
-          <label>Modo de Geração</label>
+          <label>Dificuldade</label>
           <div className="radio-group">
             <div className="radio-item">
               <input
                 type="radio"
-                id="mode-basic"
+                id="difficulty-easy"
-                name="mode"
+                name="difficulty"
-                value="Basic"
+                value="Easy"
-                checked={mode === 'Basic'}
+                checked={difficulty === 'Easy'}
-                onChange={(e) => handleModeChange((e.target as HTMLInputElement).value as FlashcardMode)}
+                onChange={() => setDifficulty('Easy')}
               />
-              <label htmlFor="mode-basic" className="radio-label" title="Modo básico, rápido e simples. Geralmente conteúdos simples e repetíveis">Básico</label>
+              <label htmlFor="difficulty-easy" className="radio-label" title="Perguntas mais diretas e objetivas">
+                Facil
+              </label>
             </div>
             <div className="radio-item">
               <input
                 type="radio"
-                id="mode-simple"
+                id="difficulty-hard"
-                name="mode"
+                name="difficulty"
-                value="Simple"
+                value="Hard"
-                checked={mode === 'Simple'}
+                checked={difficulty === 'Hard'}
-                onChange={(e) => handleModeChange((e.target as HTMLInputElement).value as FlashcardMode)}
+                onChange={() => setDifficulty('Hard')}
               />
-              <label htmlFor="mode-simple" className="radio-label" title="Modo rápido e simples, possui uma melhor compreensão">Simples</label>
+              <label htmlFor="difficulty-hard" className="radio-label" title="Perguntas mais desafiadoras">
-            </div>
+                Dificil
-            <div className="radio-item">
+              </label>
-              <input
-                type="radio"
-                id="mode-detailed"
-                name="mode"
-                value="Detailed"
-                checked={mode === 'Detailed'}
-                onChange={(e) => handleModeChange((e.target as HTMLInputElement).value as FlashcardMode)}
-              />
-              <label htmlFor="mode-detailed" className="radio-label" title="Modelo avançado, maior gama de detalhes">Detalhado</label>
-            </div>
-            <div className="radio-item">
-              <input
-                type="radio"
-                id="mode-hyper"
-                name="mode"
-                value="Hyper"
-                checked={mode === 'Hyper'}
-                onChange={(e) => handleModeChange((e.target as HTMLInputElement).value as FlashcardMode)}
-              />
-              <label htmlFor="mode-hyper" className="radio-label" title="Modelo Pro, complexo e com perguntas adicionais">Hiper</label>
             </div>
           </div>
         </div>
 
         <Button variant="primary" onClick={handleGenerate} disabled={loading} style={{ marginTop: '1rem' }}>
-          {loading ? 'Gerando...' : 'Gerar Flashcards e Baixar (CSV)'}
+          {loading ? 'Gerando...' : 'Gerar Bibliotecas de Flashcards'}
         </Button>
 
-        {error && <div style={{ color: '#ff7b72', marginTop: '1rem' }}>{error}</div>}
+        {error && <div className="flashcard-error">{error}</div>}
-        {success && <div className="success-message">Flashcards gerados com sucesso! O download deve ter começado.</div>}
       </div>
 
       {loading && (
         <div className="spinner-container">
           <div className="spinner"></div>
-          <p>Extraindo os melhores conceitos para os seus flashcards. Aguarde...</p>
+          <p>Gerando os flashcards com IA e salvando no banco. Aguarde...</p>
+        </div>
+      )}
+
+      {generatedLibraries.length > 0 && (
+        <div className="flashcard-result-panel">
+          <h3>Bibliotecas Geradas</h3>
+          <div className="flashcard-result-list">
+            {generatedLibraries.map((library) => (
+              <article key={library.id} className="flashcard-result-item">
+                <div className="flashcard-result-header">
+                  <strong>{library.fileName}</strong>
+                  <span>{library.cardCount} cards</span>
+                </div>
+                <div className="flashcard-result-meta">
+                  <span>Materia: {library.subject}</span>
+                  <span>Dificuldade: {difficultyLabel(library.difficulty)}</span>
+                </div>
+              </article>
+            ))}
+          </div>
         </div>
       )}
     </div>

Mindforge.Web/src/components/FlashcardReviewComponent.css

@@ -0,0 +1,171 @@
+.review-container {
+  width: 100%;
+  max-width: 900px;
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 1.2rem;
+  animation: slideUp 0.45s ease-out;
+}
+
+.review-title {
+  font-size: 2.35rem;
+}
+
+.review-error {
+  color: #ff9c96;
+  text-align: left;
+  background: rgba(255, 69, 58, 0.12);
+  border: 1px solid rgba(255, 69, 58, 0.4);
+  border-radius: 10px;
+  padding: 0.8rem 1rem;
+}
+
+.review-select-panel,
+.review-session-panel {
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 12px;
+  padding: 1.25rem;
+  text-align: left;
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  box-shadow: 0 14px 36px rgba(0, 0, 0, 0.18);
+}
+
+.review-state {
+  color: rgba(255, 255, 255, 0.72);
+  font-size: 0.95rem;
+}
+
+.review-subjects {
+  display: grid;
+  gap: 1rem;
+}
+
+.review-subject-section {
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  background: rgba(0, 0, 0, 0.18);
+  border-radius: 10px;
+  padding: 0.9rem;
+}
+
+.review-subject-section h3 {
+  margin: 0 0 0.8rem;
+  font-size: 1rem;
+  color: rgba(255, 255, 255, 0.95);
+}
+
+.review-library-list {
+  display: grid;
+  gap: 0.6rem;
+}
+
+.review-library-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.7rem;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 10px;
+  padding: 0.6rem 0.7rem;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.03);
+}
+
+.review-library-item input[type="checkbox"] {
+  margin-top: 0.15rem;
+  width: 16px;
+  height: 16px;
+  accent-color: var(--color-accent);
+}
+
+.review-library-texts {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+}
+
+.review-library-texts strong {
+  font-size: 0.95rem;
+}
+
+.review-library-texts span {
+  color: rgba(255, 255, 255, 0.68);
+  font-size: 0.84rem;
+}
+
+.review-actions {
+  margin-top: 1rem;
+  display: flex;
+  justify-content: flex-end;
+}
+
+.review-progress {
+  display: flex;
+  align-items: center;
+  gap: 0.9rem;
+  margin-bottom: 0.8rem;
+}
+
+.review-progress span {
+  font-size: 0.9rem;
+  color: rgba(255, 255, 255, 0.8);
+  min-width: 60px;
+}
+
+.review-progress-bar {
+  width: 100%;
+  height: 8px;
+  border-radius: 999px;
+  background: rgba(0, 0, 0, 0.25);
+  overflow: hidden;
+}
+
+.review-progress-fill {
+  height: 100%;
+  background: linear-gradient(90deg, rgba(var(--color-accent-rgb), 0.8), rgba(var(--color-accent-rgb), 1));
+  border-radius: 999px;
+  transition: width 0.25s ease;
+}
+
+.review-card {
+  border: 1px solid rgba(255, 255, 255, 0.16);
+  border-radius: 10px;
+  padding: 1rem;
+  background: rgba(0, 0, 0, 0.2);
+  min-height: 250px;
+}
+
+.review-card header {
+  margin-bottom: 0.8rem;
+}
+
+.review-card small {
+  color: rgba(255, 255, 255, 0.62);
+}
+
+.review-card h3 {
+  margin: 0 0 0.4rem;
+  font-size: 0.98rem;
+  color: rgba(255, 255, 255, 0.9);
+}
+
+.review-card p {
+  margin: 0 0 1rem;
+  font-size: 1rem;
+  line-height: 1.55;
+}
+
+.review-session-actions {
+  margin-top: 1rem;
+  display: flex;
+  gap: 0.65rem;
+  flex-wrap: wrap;
+}
+
+@media (max-width: 740px) {
+  .review-session-actions {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}

Mindforge.Web/src/components/FlashcardReviewComponent.tsx

@@ -0,0 +1,233 @@
+import { useEffect, useMemo, useState } from 'preact/hooks';
+import {
+  MindforgeApiService,
+  type FlashcardCard,
+  type FlashcardLibrarySummary,
+} from '../services/MindforgeApiService';
+import { Button } from './Button';
+import './FlashcardReviewComponent.css';
+
+function groupLibrariesBySubject(libraries: FlashcardLibrarySummary[]) {
+  const grouped: Record<string, FlashcardLibrarySummary[]> = {};
+  libraries.forEach((library) => {
+    const subject = library.subject || 'Geral';
+    if (!grouped[subject]) {
+      grouped[subject] = [];
+    }
+    grouped[subject].push(library);
+  });
+
+  return Object.entries(grouped).sort(([a], [b]) => a.localeCompare(b));
+}
+
+function difficultyLabel(difficulty: string) {
+  return difficulty === 'Hard' ? 'Dificil' : 'Facil';
+}
+
+export function FlashcardReviewComponent() {
+  const [libraries, setLibraries] = useState<FlashcardLibrarySummary[]>([]);
+  const [selectedLibraryIds, setSelectedLibraryIds] = useState<number[]>([]);
+  const [loadingLibraries, setLoadingLibraries] = useState(true);
+  const [loadingSession, setLoadingSession] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [sessionCards, setSessionCards] = useState<FlashcardCard[]>([]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [showAnswer, setShowAnswer] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadLibraries() {
+      setLoadingLibraries(true);
+      setError(null);
+
+      try {
+        const result = await MindforgeApiService.getFlashcardLibraries();
+        if (!cancelled) {
+          setLibraries(result);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setError(err?.message || 'Falha ao carregar bibliotecas de flashcards.');
+        }
+      } finally {
+        if (!cancelled) {
+          setLoadingLibraries(false);
+        }
+      }
+    }
+
+    loadLibraries();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const groupedLibraries = useMemo(() => groupLibrariesBySubject(libraries), [libraries]);
+
+  const libraryById = useMemo(() => {
+    return new Map(libraries.map((library) => [library.id, library]));
+  }, [libraries]);
+
+  const currentCard = sessionCards[currentIndex];
+  const progressPercent = sessionCards.length > 0
+    ? ((currentIndex + 1) / sessionCards.length) * 100
+    : 0;
+
+  const toggleLibrary = (libraryId: number) => {
+    if (selectedLibraryIds.includes(libraryId)) {
+      setSelectedLibraryIds(selectedLibraryIds.filter((id) => id !== libraryId));
+      return;
+    }
+
+    setSelectedLibraryIds([...selectedLibraryIds, libraryId]);
+  };
+
+  const startReviewSession = async () => {
+    if (selectedLibraryIds.length === 0) {
+      setError('Selecione ao menos uma biblioteca para iniciar a revisao.');
+      return;
+    }
+
+    setLoadingSession(true);
+    setError(null);
+
+    try {
+      const response = await MindforgeApiService.createFlashcardReviewSession({
+        libraryIds: selectedLibraryIds,
+      });
+
+      setSessionCards(response.cards);
+      setCurrentIndex(0);
+      setShowAnswer(false);
+    } catch (err: any) {
+      setError(err?.message || 'Falha ao iniciar sessao de revisao.');
+    } finally {
+      setLoadingSession(false);
+    }
+  };
+
+  const endSession = () => {
+    setSessionCards([]);
+    setCurrentIndex(0);
+    setShowAnswer(false);
+  };
+
+  const goToPrevious = () => {
+    if (currentIndex === 0) {
+      return;
+    }
+    setCurrentIndex(currentIndex - 1);
+    setShowAnswer(false);
+  };
+
+  const goToNext = () => {
+    if (currentIndex >= sessionCards.length - 1) {
+      return;
+    }
+    setCurrentIndex(currentIndex + 1);
+    setShowAnswer(false);
+  };
+
+  return (
+    <div className="review-container">
+      <h2 className="title review-title">Revisao Flashcards</h2>
+      <p className="subtitle">Escolha as bibliotecas para estudar e inicie uma sessao de revisao.</p>
+
+      {error && <div className="review-error">{error}</div>}
+
+      {sessionCards.length === 0 && (
+        <div className="review-select-panel">
+          {loadingLibraries && <p className="review-state">Carregando bibliotecas...</p>}
+          {!loadingLibraries && libraries.length === 0 && (
+            <p className="review-state">Nenhuma biblioteca encontrada. Gere flashcards para comecar.</p>
+          )}
+
+          {!loadingLibraries && libraries.length > 0 && (
+            <div className="review-subjects">
+              {groupedLibraries.map(([subject, subjectLibraries]) => (
+                <section key={subject} className="review-subject-section">
+                  <h3>{subject}</h3>
+                  <div className="review-library-list">
+                    {subjectLibraries.map((library) => (
+                      <label key={library.id} className="review-library-item">
+                        <input
+                          type="checkbox"
+                          checked={selectedLibraryIds.includes(library.id)}
+                          onChange={() => toggleLibrary(library.id)}
+                        />
+                        <div className="review-library-texts">
+                          <strong>{library.fileName}</strong>
+                          <span>
+                            {library.cardCount} cards - {difficultyLabel(library.difficulty)}
+                          </span>
+                        </div>
+                      </label>
+                    ))}
+                  </div>
+                </section>
+              ))}
+            </div>
+          )}
+
+          <div className="review-actions">
+            <Button variant="primary" onClick={startReviewSession} disabled={loadingSession || selectedLibraryIds.length === 0}>
+              {loadingSession ? 'Iniciando...' : 'Iniciar Revisao'}
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {sessionCards.length > 0 && currentCard && (
+        <div className="review-session-panel">
+          <div className="review-progress">
+            <span>{currentIndex + 1} / {sessionCards.length}</span>
+            <div className="review-progress-bar">
+              <div className="review-progress-fill" style={{ width: `${progressPercent}%` }} />
+            </div>
+          </div>
+
+          <article className="review-card">
+            <header>
+              <small>
+                {libraryById.get(currentCard.libraryId)?.fileName || 'Arquivo'} -
+                {' '}
+                {libraryById.get(currentCard.libraryId)?.subject || 'Geral'}
+              </small>
+            </header>
+            <h3>Frente</h3>
+            <p>{currentCard.front}</p>
+            {showAnswer && (
+              <>
+                <h3>Verso</h3>
+                <p>{currentCard.back}</p>
+              </>
+            )}
+          </article>
+
+          <div className="review-session-actions">
+            <Button variant="secondary" onClick={goToPrevious} disabled={currentIndex === 0}>
+              Anterior
+            </Button>
+
+            {!showAnswer && (
+              <Button variant="primary" onClick={() => setShowAnswer(true)}>
+                Revelar Resposta
+              </Button>
+            )}
+
+            {showAnswer && (
+              <Button variant="primary" onClick={goToNext} disabled={currentIndex >= sessionCards.length - 1}>
+                Proximo
+              </Button>
+            )}
+
+            <Button variant="secondary" onClick={endSession}>
+              Encerrar Sessao
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

Mindforge.Web/src/components/Sidebar.tsx

@@ -2,15 +2,15 @@ import { Button } from './Button';
 import './Sidebar.css';
 
 interface SidebarProps {
-  onModuleChange: (module: 'home' | 'verificador' | 'flashcards') => void;
+  onModuleChange: (module: 'home' | 'verificador' | 'flashcards' | 'revisao-flashcards') => void;
-  activeModule: 'home' | 'verificador' | 'flashcards';
+  activeModule: 'home' | 'verificador' | 'flashcards' | 'revisao-flashcards';
 }
 
 export function Sidebar({ onModuleChange, activeModule }: SidebarProps) {
   return (
     <aside class="sidebar">
       <div class="sidebar-header">
-        <h2 class="sidebar-title">Módulos</h2>
+        <h2 class="sidebar-title">Modulos</h2>
       </div>
       <div class="sidebar-nav">
         <Button
@@ -27,6 +27,13 @@ export function Sidebar({ onModuleChange, activeModule }: SidebarProps) {
         >
           Flashcards
         </Button>
+        <Button
+          variant={activeModule === 'revisao-flashcards' ? 'primary' : 'secondary'}
+          onClick={() => onModuleChange('revisao-flashcards')}
+          className="sidebar-btn"
+        >
+          Revisao Flashcards
+        </Button>
       </div>
     </aside>
   );

Mindforge.Web/src/services/MindforgeApiService.ts

@@ -26,17 +26,66 @@ export interface CheckFileResponse {
   result: string;
 }
 
+export type FlashcardDifficulty = 'Easy' | 'Hard';
+
 export interface GenerateFlashcardsRequest {
-  fileContent: string;
+  filePaths: string[];
-  fileName: string;
   amount: number;
-  mode: FlashcardMode;
+  difficulty: FlashcardDifficulty;
 }
 
-export type FlashcardMode = 'Basic' | 'Simple' | 'Detailed' | 'Hyper';
+export interface FlashcardCard {
+  id: number;
+  libraryId: number;
+  front: string;
+  back: string;
+  position: number;
+  createdAt: string;
+}
+
+export interface FlashcardLibrarySummary {
+  id: number;
+  filePath: string;
+  fileName: string;
+  subject: string;
+  difficulty: string;
+  cardCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface FlashcardLibraryDetails extends FlashcardLibrarySummary {
+  cards: FlashcardCard[];
+}
 
 export interface GenerateFlashcardsResponse {
-  result: string;
+  libraries: FlashcardLibraryDetails[];
+}
+
+export interface FlashcardReviewSessionRequest {
+  libraryIds: number[];
+}
+
+export interface FlashcardReviewSessionResponse {
+  cards: FlashcardCard[];
+}
+
+async function throwIfNotOk(response: Response, fallback: string) {
+  if (response.ok) {
+    return;
+  }
+
+  let apiMessage = '';
+  try {
+    const body = await response.json();
+    if (typeof body?.error === 'string' && body.error.length > 0) {
+      apiMessage = body.error;
+    }
+  } catch {
+    // Ignore parse failures and throw fallback below.
+  }
+
+  throw new Error(apiMessage || fallback);
 }
 
 export const MindforgeApiService = {
@@ -49,9 +98,7 @@ export const MindforgeApiService = {
       body: JSON.stringify(data),
     });
 
-    if (!response.ok) {
+    await throwIfNotOk(response, `Erro ao validar arquivo: ${response.statusText}`);
-      throw new Error(`Error checking file: ${response.statusText}`);
-    }
     return response.json();
   },
 
@@ -64,27 +111,50 @@ export const MindforgeApiService = {
       body: JSON.stringify(data),
     });
 
-    if (!response.ok) {
+    await throwIfNotOk(response, `Erro ao gerar flashcards: ${response.statusText}`);
-      throw new Error(`Error generating flashcards: ${response.statusText}`);
+    return response.json();
-    }
+  },
+
+  async getFlashcardLibraries(): Promise<FlashcardLibrarySummary[]> {
+    const response = await fetch(`${BASE_URL}/api/v1/flashcard/libraries`);
+    await throwIfNotOk(response, `Erro ao buscar bibliotecas de flashcards: ${response.statusText}`);
+    return response.json();
+  },
+
+  async getFlashcardLibrary(id: number): Promise<FlashcardLibraryDetails> {
+    const response = await fetch(`${BASE_URL}/api/v1/flashcard/libraries/${id}`);
+    await throwIfNotOk(response, `Erro ao buscar biblioteca ${id}: ${response.statusText}`);
+    return response.json();
+  },
+
+  async createFlashcardReviewSession(data: FlashcardReviewSessionRequest): Promise<FlashcardReviewSessionResponse> {
+    const response = await fetch(`${BASE_URL}/api/v1/flashcard/review-session`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    await throwIfNotOk(response, `Erro ao iniciar revisao: ${response.statusText}`);
     return response.json();
   },
 
   async getRepositoryInfo(): Promise<RepositoryInfo> {
     const response = await fetch(`${BASE_URL}/api/v1/repository/info`);
-    if (!response.ok) throw new Error(`Error fetching repository info: ${response.statusText}`);
+    await throwIfNotOk(response, `Erro ao buscar info do repositorio: ${response.statusText}`);
     return response.json();
   },
 
   async getRepositoryTree(): Promise<FileTreeNode[]> {
     const response = await fetch(`${BASE_URL}/api/v1/repository/tree`);
-    if (!response.ok) throw new Error(`Error fetching repository tree: ${response.statusText}`);
+    await throwIfNotOk(response, `Erro ao buscar arvore do repositorio: ${response.statusText}`);
     return response.json();
   },
 
   async getFileContent(path: string): Promise<FileContentResponse> {
     const response = await fetch(`${BASE_URL}/api/v1/repository/file?path=${encodeURIComponent(path)}`);
-    if (!response.ok) throw new Error(`Error fetching file ${path}: ${response.statusText}`);
+    await throwIfNotOk(response, `Erro ao buscar arquivo ${path}: ${response.statusText}`);
     return response.json();
   },
 };

dev.ps1

@@ -0,0 +1,11 @@
+# Starting Mindforge Development Environment
+
+# Start API
+Write-Host "Starting Mindforge.API..." -ForegroundColor Cyan
+Start-Process powershell -ArgumentList "-NoExit", "-Command", "dotnet run --project Mindforge.API"
+
+# Start Web
+Write-Host "Starting Mindforge.Web..." -ForegroundColor Cyan
+Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd Mindforge.Web; npm run dev"
+
+Write-Host "Both projects are starting in separate windows." -ForegroundColor Green

dev.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# Function to handle script termination
+cleanup() {
+    echo "Shutting down..."
+    kill $(jobs -p)
+    exit
+}
+
+trap cleanup SIGINT SIGTERM
+
+echo "Starting Mindforge.API..."
+(cd Mindforge.API && dotnet run) &
+
+echo "Starting Mindforge.Web..."
+(cd Mindforge.Web && npm run dev) &
+
+echo "Both projects are running. Press Ctrl+C to stop both."
+wait

project-context.md

@@ -0,0 +1,368 @@
+# Mindforge
+
+## Visao Geral (Overview)
+
+Mindforge e uma ferramenta de estudo para auxiliar na preparacao para concursos publicos brasileiros. O sistema permite validar e gerar materiais de estudo a partir de arquivos Markdown hospedados em repositorios Git, utilizando IA (OpenRouter/OpenAI-compatible API) para processamento.
+
+A interface e em **portugues brasileiro** e possui um tema escuro com efeito vidro ("glassy-look").
+
+---
+
+## Tech Stack
+
+### Frontend (Mindforge.Web)
+| Tecnologia | Versao | Finalidade |
+|---|---|---|
+| **Preact** | ^10.29.0 | UI library (lightweight React alternative) |
+| **Vite** | ^8.0.1 | Build tool e dev server |
+| **TypeScript** | ~5.9.3 | Tipagem estatica |
+| **marked** | ^17.0.4 | Renderizacao Markdown -> HTML |
+| **diff** | ^8.0.3 | Diff de texto (word-level) |
+| **Google Fonts (Lato)** | 300/400/700 | Tipografia da interface |
+
+### Backend API (Mindforge.API)
+| Tecnologia | Versao | Finalidade |
+|---|---|---|
+| **.NET 9** | net9.0 | ASP.NET Core Web API |
+| **C#** | - | Linguagem |
+| **Microsoft.AspNetCore.OpenApi** | 9.0.12 | Suporte OpenAPI/Swagger |
+
+### Cronjob (mindforge.cronjob)
+| Tecnologia | Versao | Finalidade |
+|---|---|---|
+| **Go** | 1.22 | Linguagem |
+| **godotenv** | v1.5.1 | Carregamento de arquivos .env |
+
+### Infraestrutura
+| Tecnologia | Finalidade |
+|---|---|
+| **Docker** | Imagens multi-arch (amd64, arm64) |
+| **Kubernetes** | Orquestracao (Deployments, CronJobs, Services, Ingress) |
+| **Gitea** | Git hosting + Container registry (`git.ivanch.me`) |
+| **Gitea Actions** | CI/CD (build & deploy no push para main) |
+| **Nginx Ingress** | K8s ingress controller |
+| **OpenRouter API** | Provedor LLM (endpoint OpenAI-compatible) |
+
+---
+
+## Arquitetura (Architecture)
+
+O projeto e um **monorepo** com tres servicos independentes e deployaveis separadamente.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Kubernetes Cluster                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
+│  │ mindforge-web │  │ mindforge-api│  │ cronjob   │ │
+│  │  (Preact SPA) │──│ (.NET 9 API) │  │ (Go app)  │ │
+│  │  port 80      │  │ port 8080    │  │ (weekly)  │ │
+│  └──────────────┘  └──────┬───────┘  └─────┬─────┘ │
+│        │                  │                 │       │
+│   mindforge.haven    api.mindforge.haven    │       │
+└──────────────────────────┼─────────────────┼───────┘
+                           │                 │
+                    ┌──────┴───────┐  ┌──────┴───────┐
+                    │  OpenRouter  │  │    Gitea     │
+                    │  (OpenAI API)│  │ (Git repos)  │
+                    └──────────────┘  └──────┬───────┘
+                                             │
+                                    ┌────────┴────────┐
+                                    │   Discord        │
+                                    │   Webhooks       │
+                                    └─────────────────┘
+```
+
+### Servicos
+
+#### 1. Mindforge.Web (Frontend)
+- **Tipo**: Single Page Application (SPA)
+- **Funcao**: Interface do usuario para validacao de arquivos e geracao de flashcards
+- **Modulos**: Home, Verificador, Flashcards
+- **Roteamento**: State-based manual via `useState` (nao usa react-router). Componentes sao alternados com `display: block/none`.
+- **Estado**: Apenas `useState`/`useEffect` locais. Sem store global, sem Context API.
+
+#### 2. Mindforge.API (Backend)
+- **Tipo**: REST API
+- **Padrao arquitetural**: Clean layered architecture
+  - **Controllers** -> validacao e roteamento HTTP
+  - **Services** -> logica de negocio (FileService, FlashcardService, AgentService, GiteaService)
+  - **Providers** -> abstracao de APIs externas (OpenAIApiProvider implementa ILlmApiProvider)
+  - **Middlewares** -> cross-cutting concerns (ExceptionHandlingMiddleware)
+  - **Models** -> DTOs e tipos de request/response
+- **DI**: Todos servicos e providers registrados como Scoped
+- **CORS**: Allow all origins
+- **Auth**: Nenhuma no momento
+
+#### 3. Mindforge.Cronjob (Background Worker)
+- **Tipo**: Kubernetes CronJob
+- **Schedule**: Sabados as 9:00 AM
+- **Pipeline**:
+  1. Clona repositorio Git via SSH
+  2. Encontra arquivos modificados nos ultimos 7 dias (`.md`, exceto `Conteudos.md`)
+  3. Filtra commits de "refactor" via `git log`
+  4. Ranqueia por linhas alteradas, seleciona top N (default 10)
+  5. Gera resumo em texto com IA para cada arquivo
+  6. Formata resumo em Markdown
+  7. Envia para Discord via webhook (chunked em 1800 chars)
+- **Error handling**: Reporta ao Haven Notify
+
+### Decisoes de Arquitetura (Architecture Decisions)
+
+1. **Sem banco de dados**: Totalmente stateless. Conteudo de estudo vive em repositorios Git, acessados via Gitea API em tempo de request.
+2. **Git como content store**: Nao ha upload de arquivos - o conteudo e lido diretamente do repositorio Git.
+3. **IA como engine de processamento**: Toda validacao e geracao e delegada ao LLM via OpenRouter.
+4. **Provider abstraction**: `ILlmApiProvider` permite trocar o backend de IA sem alterar a logica de negocio.
+5. **Monorepo com deploys independentes**: Cada servico tem seu proprio Dockerfile, manifesto K8s e pipeline CI.
+6. **Roteamento manual no frontend**: Sem lib de router, toggle de visibilidade via estado.
+7. **Preact em vez de React**: Bundle size menor.
+
+---
+
+## Estrutura do Projeto (Project Structure)
+
+```
+mindforge/
+├── AGENTS.md                          # Instrucoes para agentes AI
+├── project-context.md                 # Este arquivo - fonte da verdade do projeto
+├── README.md
+├── mindforge.png                      # Logo do projeto
+├── dev.ps1 / dev.sh                   # Scripts de inicializacao dev
+├── .gitea/workflows/                  # CI/CD pipelines
+│   ├── mindforge-api.yaml
+│   ├── mindforge-web.yaml
+│   └── mindforge-cronjob.yaml
+│
+├── Mindforge.API/                     # Backend .NET 9
+│   ├── Program.cs                     # Entry point: DI, CORS, middleware
+│   ├── Controllers/
+│   │   ├── FileController.cs          # POST /api/v1/file/check
+│   │   ├── FlashcardController.cs     # POST /api/v1/flashcard/generate
+│   │   └── RepositoryController.cs    # GET /api/v1/repository/*
+│   ├── Services/                      # Logica de negocio
+│   │   ├── AgentService.cs
+│   │   ├── FileService.cs
+│   │   ├── FlashcardService.cs
+│   │   ├── GiteaService.cs
+│   │   └── Interfaces/
+│   ├── Providers/
+│   │   ├── ILlmApiProvider.cs         # Interface do provedor LLM
+│   │   └── OpenAIApiProvider.cs       # Implementacao OpenAI/OpenRouter com retry
+│   ├── Middlewares/
+│   │   └── ExceptionHandlingMiddleware.cs
+│   ├── Models/
+│   │   ├── FileTreeNode.cs
+│   │   └── Requests/                  # DTOs de request
+│   ├── Exceptions/
+│   │   └── UserException.cs           # 400 Bad Request customizado
+│   └── deploy/
+│       └── mindforge-api.yaml         # Manifest K8s (Deployment + Service + Ingress)
+│
+├── Mindforge.Web/                     # Frontend Preact + Vite
+│   ├── vite.config.ts
+│   ├── tsconfig.app.json              # Target ES2023, JSX preact, strict mode
+│   ├── .env                           # VITE_API_BASE_URL=http://localhost:5123
+│   ├── src/
+│   │   ├── main.tsx                   # Entry point
+│   │   ├── app.tsx                    # Componente raiz: header, sidebar, modulos
+│   │   ├── app.css                    # Estilos hero, animacoes
+│   │   ├── index.css                  # CSS variables, reset, layout base
+│   │   ├── services/
+│   │   │   └── MindforgeApiService.ts  # Cliente API (fetch, interfaces tipadas)
+│   │   └── components/
+│   │       ├── Button.tsx / .css      # Botao reutilizavel (primary/secondary)
+│   │       ├── Header.tsx / .css      # Header fixo com logo + nome do repo
+│   │       ├── Sidebar.tsx / .css     # Navegacao lateral
+│   │       ├── VerificadorComponent.tsx / .css  # Validador de arquivos
+│   │       ├── FlashcardComponent.tsx / .css    # Gerador de flashcards
+│   │       └── FileTreeComponent.tsx / .css     # Arvore de arquivos do repo
+│   └── deploy/
+│       └── mindforge-web.yaml         # Manifest K8s
+│
+└── mindforge.cronjob/                 # CronJob em Go
+    ├── cmd/mindforge.cronjob/main.go   # Entry point
+    ├── internal/
+    │   ├── agent/agent.go              # Cria e formata resumos
+    │   ├── llm/                        # Servico LLM
+    │   ├── git/git.go                  # Clone, diff, SSH
+    │   ├── errors/errors.go            # Reporte de erros
+    │   └── message/messages.go         # Notificacoes Discord
+    └── deploy/
+        └── mindforge-cronjob.yaml      # Manifest K8s CronJob
+```
+
+---
+
+## API Endpoints
+
+### File Controller (`/api/v1/file`)
+| Metodo | Rota | Descricao |
+|---|---|---|
+| POST | `/api/v1/file/check` | Valida linguagem ou conteudo de um arquivo |
+
+```json
+// Request
+{
+  "fileContent": "string (conteudo do arquivo)",
+  "fileName": "string",
+  "checkType": "language" | "content"
+}
+
+// Response
+{
+  "result": "string (resultado da validacao)"
+}
+```
+
+### Flashcard Controller (`/api/v1/flashcard`)
+| Metodo | Rota | Descricao |
+|---|---|---|
+| POST | `/api/v1/flashcard/generate` | Gera flashcards em CSV |
+
+```json
+// Request
+{
+  "fileContent": "string",
+  "fileName": "string",
+  "amount": 10,
+  "mode": "Basic" | "Simple" | "Detailed" | "Hyper"
+}
+
+// Response
+{
+  "result": "string (CSV: Frente;Verso\nFrente;Verso\n...)"
+}
+```
+
+### Repository Controller (`/api/v1/repository`)
+| Metodo | Rota | Descricao |
+|---|---|---|
+| GET | `/api/v1/repository/info` | Nome do repositorio |
+| GET | `/api/v1/repository/tree` | Arvore de arquivos do repositorio |
+| GET | `/api/v1/repository/file?path=...` | Conteudo de um arquivo especifico |
+
+---
+
+## Convencoes de Desenvolvimento (Development Conventions)
+
+### Frontend (Preact/TypeScript)
+- **Componentes**: Funcoes nomeadas exportadas com `export function Nome()`. Sem `export default`.
+- **Props**: Interfaces TypeScript definidas no mesmo arquivo do componente.
+- **Hooks**: `useState`, `useEffect` importados de `preact/hooks`.
+- **Children**: Tipados como `ComponentChildren` de `preact`.
+- **CSS**: Um arquivo `.css` por componente, importado diretamente. **Sem CSS Modules.**
+- **Estado**: Apenas estado local (`useState`). Sem store global, sem Context API.
+- **Roteamento**: Alternancia de componentes via `display: block/none` com estado `activeModule`. Nao usa react-router.
+- **API**: Chamadas via `MindforgeApiService` (objeto singleton com metodos estaticos usando `fetch`).
+- **TypeScript**: Strict mode, `erasableSyntaxOnly`, `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`.
+- **Alias**: `react` e `react-dom` mapeados para `preact/compat/` no tsconfig.
+
+### Backend (C#/.NET 9)
+- **Namespaces**: `Mindforge.API.Controllers`, `Mindforge.API.Services`, etc.
+- **Interfaces**: Prefixo `I` (ex: `IFileService`, `ILlmApiProvider`).
+- **DI**: Todos servicos registrados como `Scoped` em `Program.cs`.
+- **Controllers**: Atributo `[Route("api/v1/...")]`. Metodos retornam `IActionResult`.
+- **Tratamento de erros**: `ExceptionHandlingMiddleware` captura `UserException` (400) e excecoes genericas (500).
+
+### UI/UX
+- **Idioma**: Todo texto em **portugues brasileiro**.
+- **Tema**: Escuro com efeito vidro (glassy). `backdrop-filter: blur()`, fundos `rgba` semitransparentes.
+- **Botoes**: Estilo iOS-like, modernos. Variantes `primary` (com blur) e `secondary` (transparente).
+- **Tipografia**: Lato (Google Fonts), pesos 300/400/700.
+- **Background**: `#005873` (azul petroleo escuro). Nao muito escuro.
+
+### CSS Variables (definidas em `index.css`)
+```css
+--color-bg: #005873;
+--color-header: #0f0f0f;
+--color-sidebar: #013a4c;
+--color-text-creamy: #f4f5f5;
+--color-accent: #00b4d8;
+--color-accent-rgb: 0, 180, 216;
+--color-accent-hover: #0096c7;
+--font-main: 'Lato', sans-serif;
+```
+
+### Git
+- Branches: `main` (producao)
+- CI/CD: Gitea Actions dispara no push para main, build com Docker Buildx multi-arch, push para Gitea Container Registry, deploy no K8s.
+
+---
+
+## Configuracao & Environment Variables
+
+### API (Mindforge.API)
+| Variavel | Descricao |
+|---|---|
+| `OPENAI_API_URL` | URL do endpoint OpenAI-compatible (OpenRouter) |
+| `OPENAI_TOKEN` | Token de autenticacao da API |
+| `OPENAI_MODEL` | Modelo LLM a ser usado |
+| `GITEA_REPO_URL` | URL do repositorio Gitea |
+| `GITEA_ACCESS_TOKEN` | Token de acesso ao Gitea |
+
+### Web (Mindforge.Web)
+| Variavel | Descricao |
+|---|---|
+| `VITE_API_BASE_URL` | URL base da API (default: `http://localhost:5123`) |
+
+### Cronjob
+| Variavel | Descricao |
+|---|---|
+| `GIT_REPOSITORY` | URL do repo Git a clonar |
+| `DISCORD_WEBHOOK_URL` | Webhook do Discord para notificacoes |
+| `OPENAI_API_URL` | URL do endpoint OpenAI |
+| `OPENAI_TOKEN` | Token de autenticacao |
+| `HAVEN_NOTIFY_URL` | URL do servico de reporte de erros |
+
+## Repositório base para os arquivos
+A base do repositório para os arquivos de estudo (compartilhado pelo Obsidian) é https://git.ivanch.me/ivanch/concurso.
+Ele segue o padrão `[base]/concurso/[Matéria]/[SubMatéria*]/[Arquivo]`, onde [base] é a URL do git, concurso é o nome da pasta dentro do git base, Matéria é o nome da matéria (ex: `Direito Constitucional`), SubMatéria é o nome da submatéria (ex. `Poder Legislativo`) - podendo ser opcional e com múltiplas submatérias -, e Arquivo é o nome do arquivo (ex: `Câmara dos Deputados.md`).
+
+Exemplos:
+- [base]/Concursos/Direito Constitucional/Poder Legislativo/Câmara dos Deputados.md
+- [base]/Concursos/Direito Constitucional/Poder Legislativo/CPIs.md
+- [base]/Concursos/Direito Constitucional/Ciência, Meio Ambiente e Índios.md
+- [base]/Concursos/Direito Constitucional/Ciência, Meio Ambiente e Índios.md
+- [base]/Concursos/TI/Analise e Engenharia de Dados/Data Lake e Data Warehouse.md
+- [base]/Concursos/TI/Rede/VLAN.md
+- [base]/Concursos/TI/Rede/Email/IMAP e POP3.md
+
+---
+
+## Atualizacao - Flashcards Persistidos (2026-05-30)
+
+### Mudancas de Arquitetura
+- A API deixa de ser totalmente stateless para o dominio de flashcards.
+- Flashcards agora sao persistidos em PostgreSQL (`mindforge`) via `Dapper` + `Npgsql`.
+- O schema e criado de forma idempotente no startup da API.
+
+### Tabelas de Flashcard
+- `flashcard_libraries`: `id`, `file_path` (unico), `file_name`, `subject`, `difficulty`, `card_count`, `created_at`, `updated_at`.
+- `flashcards`: `id`, `library_id`, `front`, `back`, `position`, `created_at`.
+
+### API de Flashcards (v1)
+- `POST /api/v1/flashcard/generate`
+  Request: `{ filePaths: string[], amount: 10-30, difficulty: "Easy" | "Hard" }`
+  Comportamento: gera por arquivo selecionado, substitui biblioteca anterior do mesmo `file_path` e retorna bibliotecas com cards.
+- `GET /api/v1/flashcard/libraries`
+  Lista todas as bibliotecas persistidas, com `subject` para agrupamento na UI.
+- `GET /api/v1/flashcard/libraries/{id}`
+  Retorna detalhes de uma biblioteca com seus cards.
+- `POST /api/v1/flashcard/review-session`
+  Request: `{ libraryIds: number[] }`
+  Retorna os cards combinados para sessao de revisao (sem repeticao espaciada nesta fase).
+
+### Frontend
+- Modulo `Flashcards` atualizado para:
+  - selecionar multiplos arquivos;
+  - definir quantidade fixa por arquivo (10-30);
+  - definir dificuldade (`Facil`/`Dificil`);
+  - gerar e exibir resumo das bibliotecas salvas (sem download CSV).
+- Novo modulo `Revisao Flashcards`:
+  - lista bibliotecas agrupadas por materia (`subject`);
+  - permite selecionar multiplas bibliotecas;
+  - inicia sessao estilo Anki simplificada (frente, revelar verso, anterior/proximo, progresso visual).
+
+### Novas Configuracoes
+- `ConnectionStrings:MindforgeDb` para conexao PostgreSQL.
+- Fallback local/default:
+  `Host=localhost;Port=3307;Database=mindforge;Username=root;Password=root`.