From 909b9432dc58c859236b3550892d3a1b113af4b7 Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:29:47 -0300 Subject: [PATCH 1/8] docs(readme): fix badges, document all API ports, correct structure Badge URLs pointed at a nested workflows/pull-request/ and workflows/tests/ path that does not exist; the workflow files are flat under .github/workflows/, so every CI badge except two was a broken link. Port list only documented the .NET and Go API instances; the C++ instance on 5002 was missing. The stale kaueereinbold.github.io Pages URL and a postgres/ganache compose command missing its required profile are also corrected. --- README.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9b4da94c..84ad3382 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,9 @@ Before you begin, ensure you have the following installed on your system: Make sure the following ports are available on your system: -- **5000, 5001** - API instances +- **5000** - .NET API instance +- **5001** - Go API instance +- **5002** - C++ API instance - **5050** - MVC application - **3000** - React application - **9999** - Nginx load balancer @@ -68,8 +70,9 @@ Once all containers are running: - **React App**: [http://localhost:3000](http://localhost:3000) - **MVC App**: [http://localhost:5050](http://localhost:5050) - **API (via Load Balancer)**: [http://localhost:9999](http://localhost:9999) -- **API Instance 1**: [http://localhost:5000](http://localhost:5000) -- **API Instance 2**: [http://localhost:5001](http://localhost:5001) +- **.NET API**: [http://localhost:5000](http://localhost:5000) +- **Go API**: [http://localhost:5001](http://localhost:5001) +- **C++ API**: [http://localhost:5002](http://localhost:5002) ### Verify Everything is Running @@ -92,13 +95,13 @@ docker compose --profile all down #### Pull Request Checks - [![.NET - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/pull-request/dotnet-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/pull-request/dotnet-pull-request.yml) + [![.NET - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/dotnet-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/dotnet-pull-request.yml) - [![Go - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/pull-request/go-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/pull-request/go-pull-request.yml) + [![Go - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/go-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/go-pull-request.yml) - [![React - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/pull-request/react-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/pull-request/react-pull-request.yml) + [![React - Build & Test](https://github.com/jumperck/Reminders/actions/workflows/react-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/react-pull-request.yml) - [![Blockchain - Hardhat Tests](https://github.com/jumperck/Reminders/actions/workflows/pull-request/blockchain-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/pull-request/blockchain-pull-request.yml) + [![Blockchain - Hardhat Tests](https://github.com/jumperck/Reminders/actions/workflows/blockchain-pull-request.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/blockchain-pull-request.yml) [![Infrastructure Check](https://github.com/jumperck/Reminders/actions/workflows/pull-request-check.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/pull-request-check.yml) @@ -108,7 +111,7 @@ docker compose --profile all down [![Cypress E2E Tests](https://github.com/jumperck/Reminders/actions/workflows/cypress-e2e.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/cypress-e2e.yml) - [![.NET Code Coverage](https://github.com/jumperck/Reminders/actions/workflows/tests/dotnet-code-coverage.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/tests/dotnet-code-coverage.yml) + [![.NET Code Coverage](https://github.com/jumperck/Reminders/actions/workflows/dotnet-code-coverage.yml/badge.svg)](https://github.com/jumperck/Reminders/actions/workflows/dotnet-code-coverage.yml) ### Docker Hub @@ -163,7 +166,7 @@ This will run: Comprehensive E2E tests validate critical user interactions against the deployed application: - **Location**: `src/test/cypress/` -- **Testing Environment**: Tests run against the deployed GitHub Pages application at `https://kaueereinbold.github.io/Reminders` +- **Testing Environment**: Tests run against the deployed GitHub Pages application at `https://jumperck.github.io/Reminders` - **Coverage**: List, Create, Edit, Delete operations - **Test categories**: - List functionality (viewing reminders) @@ -188,7 +191,7 @@ For detailed testing setup and usage instructions, see: ```bash # 1. Start the API and database -docker compose up postgres ganache -d +docker compose --profile api up postgres ganache -d cd src/server/api/dotnet/Reminders.Api dotnet run From edf79662fb823388f6a3b0ca1ea08701d99348f0 Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:30:13 -0300 Subject: [PATCH 2/8] docs(contributing): align structure tree, migration model, compose commands The structure tree listed src/server/data/ and a root test/ directory that do not exist, and omitted the Go, C++, and migration-runner services. The migration section implied the API applies migrations directly, contradicting the dedicated MigrationsRunner service. The postgres/ganache compose commands were missing the required --profile flag, so postgres never actually started as written. --- CONTRIBUTING.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c81234a5..2fad6748 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,7 +47,7 @@ cp .env.example .env # Edit .env and configure your settings # Start infrastructure services -docker compose up postgres ganache -d +docker compose --profile api up postgres ganache -d # Build the API cd src/server/api/dotnet/Reminders.Api @@ -62,22 +62,25 @@ npm install ```text Reminders/ -├── blockchain/ # Hardhat smart contracts -│ ├── contracts/ # Solidity contracts -│ ├── scripts/ # Deployment scripts -│ └── test/ # Contract tests -├── docs/ # GitHub Pages documentation -├── infrastructure/ # Nginx configs, k6 tests +├── blockchain/ # Hardhat smart contracts +│ ├── contracts/ # Solidity contracts +│ ├── scripts/ # Deployment scripts +│ └── test/ # Contract tests +├── docs/ # GitHub Pages documentation +├── infrastructure/ # Nginx configs, k6 tests ├── src/ │ ├── app/ -│ │ ├── dotnet/ # ASP.NET MVC application -│ │ └── reactjs/ # Next.js React application -│ └── server/ -│ ├── api/dotnet/ # ASP.NET Core Web API -│ └── data/ # Data access layers -└── test/ # Test projects - ├── cypress/ # E2E tests - └── server/dotnet/ # API unit tests +│ │ ├── dotnet/ # ASP.NET MVC application +│ │ └── reactjs/ # Next.js React application +│ ├── server/ +│ │ ├── api/ +│ │ │ ├── dotnet/ # ASP.NET Core Web API +│ │ │ ├── go/ # Go (Gin) API +│ │ │ └── cpp/ # C++ API +│ │ └── services/dotnet/ # Migration runner service +│ └── test/ +│ ├── cypress/ # E2E tests +│ └── server/dotnet/ # API unit tests ``` ## Database Migrations @@ -91,7 +94,7 @@ The project supports both **PostgreSQL** (default) and **SQL Server**. Migration ### Expected Behavior -When starting the API with PostgreSQL (default configuration), you may see a migration error message for SQL Server migrations. **This is expected and harmless**. The PostgreSQL migrations apply successfully, and the SQL Server migration fails because you're using PostgreSQL. +Migrations are applied by a **dedicated migration runner service** (`src/server/services/dotnet/Reminders.MigrationsRunner/`), not by the API itself. Docker Compose starts `postgres`, waits for it to report healthy, then runs `migrations` to completion before either API instance starts. When PostgreSQL is the active provider (default), the runner also attempts the SQL Server migration set and logs an expected failure for it - **this is expected and harmless**. Only the PostgreSQL migrations are actually applied. ### Creating New Migrations @@ -150,7 +153,7 @@ refactor: Improve error handling ```bash # .NET API Integration Tests (requires running API) # Start API first: -docker compose up postgres ganache -d +docker compose --profile api up postgres ganache -d cd src/server/api/dotnet/Reminders.Api dotnet run & @@ -163,7 +166,7 @@ cd src/app/reactjs/reminders-app npm test # Cypress E2E Tests -cd test/cypress +cd src/test/cypress npm run cy:run # Blockchain Tests (all passing ✅) @@ -223,7 +226,7 @@ Example: [feat] Add email notification for reminders ```bash # Just the database -docker compose up postgres -d +docker compose --profile api up postgres -d # Just the blockchain docker compose up ganache -d From 76294b43c7e68f643aeeade34024c25a2bdbd52d Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:30:35 -0300 Subject: [PATCH 3/8] docs(frontend): replace boilerplate README with real setup/env/test docs Replaced the unmodified Next.js create-app boilerplate (changelog, generic 'Learn More' links, a dev-scratch note about Google Fonts being disabled in a sandbox) with real documentation: prerequisites, NEXT_PUBLIC_API_BASE_URL from .env.example, local dev vs Docker setup, test/build/lint commands from package.json, and the actual component structure under src/app/. --- src/app/reactjs/reminders-app/README.md | 115 +++++++++++++++++------- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/src/app/reactjs/reminders-app/README.md b/src/app/reactjs/reminders-app/README.md index 67a457ec..6a19619e 100644 --- a/src/app/reactjs/reminders-app/README.md +++ b/src/app/reactjs/reminders-app/README.md @@ -1,47 +1,100 @@ -# Reminders App +# Reminders App (React / Next.js) -This is a React.js application built with Next.js and TypeScript. It's a simple reminders app that allows users to create, update, and delete reminders. +The React frontend for Reminders, built with Next.js App Router, TypeScript, and Material-UI. -## Recent Updates +## Stack -- **Upgraded to React 19**: Updated React to version 19.1.0 and React DOM to 19.1.0, taking advantage of the latest React features and improvements. -- **Upgraded to Next.js 15**: Updated Next.js to version 15.3.4 for better React 19 compatibility and latest framework features. -- **Upgraded to Material-UI v7**: Updated @mui/material to version 7.1.2 for React 19 compatibility and latest design components. -- **Migrated to @tanstack/react-query**: Replaced deprecated react-query with @tanstack/react-query v5.81.5 for better performance and React 19 support. -- **Updated TypeScript types**: Updated @types/react and @types/react-dom to latest versions for React 19 compatibility. -- **Fixed UI components**: Updated Grid components to use Stack layout for better compatibility with Material-UI v7. -- **Maintained test coverage**: All existing tests pass with 99.6% code coverage after the upgrade. -- **Note**: Google Fonts import is temporarily disabled in the sandbox environment due to network restrictions. In production, uncomment the Inter font import in layout.tsx. -- Added ESLint for linting and code quality checks. The ESLint configuration includes recommended rules from ESLint, React, and TypeScript. -- Added Prettier for code formatting. The Prettier configuration ensures consistent code style across the project. -- Fixed various linting issues in the codebase. The code now adheres to the rules specified in the ESLint configuration. -- Updated the project structure to use the `@/app` alias for imports, improving the readability and maintainability of import statements. +- **Next.js 15** (App Router) + **React 19** +- **TypeScript**, strict mode enabled +- **Material-UI v7** for components +- **@tanstack/react-query** for API data fetching +- **Jest** + **React Testing Library** for unit tests -## Getting Started +## Features -First, run the development server: +- List, create, edit, and delete reminders +- Form validation on create/edit +- Toggle reminder "done" status +- Responsive layout via Material-UI + +## Prerequisites + +- Node.js 18+ +- npm (or yarn/pnpm/bun) +- A running Reminders API reachable at the URL configured below (see the repository root [README](../../../../README.md) for starting the full stack via Docker Compose) + +## Environment Variables + +Copy `.env.example` to `.env` and set: + +```bash +# Base URL the app calls for API requests +NEXT_PUBLIC_API_BASE_URL=http://localhost:9999 +``` + +- For local development against the full Docker Compose stack, use the Nginx load balancer URL (`http://localhost:9999`). +- For a GitHub Pages / production deployment, point this at your deployed API's public URL. + +## Local Development ```bash +# Install dependencies +npm install + +# Set up environment +cp .env.example .env + +# Start the dev server npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +Open [http://localhost:3000](http://localhost:3000) in your browser. The page auto-updates as you edit files under `src/app/`. + +## Running with Docker + +The app is built and served via the project's root `docker-compose.yml`/`docker-compose.override.yml`: + +```bash +# From the repository root +docker compose --profile all up react -d +``` + +`NEXT_PUBLIC_API_BASE_URL` is baked in at build time as a Docker build argument (see `Dockerfile`); set it via the root `.env` file before building. + +## Testing + +```bash +# Run unit tests (Jest + React Testing Library) +npm test + +# Run tests with coverage +npm test -- --coverage +``` + +Tests live alongside the code they cover, e.g. `src/app/components/ReminderForm/index.test.tsx`. -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +## Build -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. +```bash +npm run build +npm start +``` -## Learn More +## Linting -To learn more about Next.js, take a look at the following resources: +```bash +npm run lint +``` -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +## Project Structure -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +```text +src/app/ +├── api/ # API client, hooks, and types +├── components/ # Reusable UI components (AlertError, ReminderForm, ReminderDeleteModal) +├── constants/ # Shared constants +├── hooks/ # Custom React hooks (context, query client) +├── reminder/ # Route segments: list, create, edit (App Router) +├── services/ # Validation and other client-side services +└── util/ # Utility helpers +``` From 1e950ad77f734e42404581e729aea8d55404e4e5 Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:31:30 -0300 Subject: [PATCH 4/8] docs(services): correct Go/blockchain/cypress READMEs, drop assistant-voice notes Go README: documented endpoints used a singular /api/reminder/:id path while the service actually routes /api/reminders/:id (plural, verified in cmd/app/main.go); the id example used an integer instead of the service's uuid ids; the container-vs-host port split (8080 in-container, 5001 via Compose) was not called out; removed a leftover assistant-voice offer to generate OpenAPI docs. Cypress README: reworded the CI binary-download notice as plain CI guidance instead of sandbox framing, and corrected the GitHub Pages base URL - it pointed at a kaueereinbold.github.io handle that 404s; the live deployment (verified via cypress.config.js and the Pages workflow) is jumperck.github.io/Reminders. Blockchain README: audited npm scripts against package.json (all five match), contract filenames against blockchain/contracts/, and the scaffolding note - already accurate, no changes needed. --- src/server/api/go/reminders-api/README.md | 20 +++++++++++--------- src/test/cypress/README.md | 10 +++++----- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/src/server/api/go/reminders-api/README.md b/src/server/api/go/reminders-api/README.md index 102a7e1c..d6f66404 100644 --- a/src/server/api/go/reminders-api/README.md +++ b/src/server/api/go/reminders-api/README.md @@ -19,10 +19,10 @@ This service is a lightweight Go implementation of the Reminders API used for lo - `GET /api/reminders/count` - Returns `{ "count": }`. -- `GET /api/reminder/:id` - - Returns the reminder by `id`. +- `GET /api/reminders/:id` + - Returns the reminder by `id` (uuid). -- `POST /api/reminder` +- `POST /api/reminders` - Creates a new reminder. - Expected JSON body: ```json @@ -34,10 +34,10 @@ This service is a lightweight Go implementation of the Reminders API used for lo } ``` -- `PUT /api/reminder/:id` +- `PUT /api/reminders/:id` - Updates an existing reminder. Same body shape as POST. -- `DELETE /api/reminder/:id` +- `DELETE /api/reminders/:id` - Deletes the reminder. Responses follow standard HTTP status codes: 200 for success, 201 for created, 400 for invalid input, 404 for not found, 500 for server errors. @@ -83,14 +83,18 @@ docker build -t reminders-go-api:local . docker run --env PostgresDefaultConnection="$CONN" -p 8080:8080 reminders-go-api:local ``` +The service listens on port `8080` inside the container. In the project's Docker Compose stack this is published on host port `5001` (see `docker-compose.override.yml`). + The Docker image contains a `wait-for-dotnet.sh` helper that can be used in Compose to delay start until the .NET API is healthy. See the project `docker-compose` for usage. ## Examples +The examples below assume the service is reachable directly on port `8080` (a local `docker run` or `go run`). When running via the project's Docker Compose stack, use port `5001` instead. + Create reminder: ```bash -curl -X POST http://localhost:8080/api/reminder \ +curl -X POST http://localhost:8080/api/reminders \ -H 'Content-Type: application/json' \ -d '{"title":"Buy milk","description":"2 liters","limitDate":"2030-12-12T00:00:00Z","isDone":false}' ``` @@ -104,12 +108,10 @@ curl http://localhost:8080/api/reminders Get by id: ```bash -curl http://localhost:8080/api/reminder/1 +curl http://localhost:8080/api/reminders/3fa85f64-5717-4562-b3fc-2c963f66afa6 ``` ## Notes - The service adds an `X-Server: go` response header to help distinguish responses when load-balanced with the .NET API. - For production or CI, prefer running the service inside the project's Docker Compose stack which configures networking and DB initialization. - -If you want OpenAPI/Swagger documentation added, I can generate a minimal spec or add annotations to the handlers. diff --git a/src/test/cypress/README.md b/src/test/cypress/README.md index e2d63ccd..b80c7310 100644 --- a/src/test/cypress/README.md +++ b/src/test/cypress/README.md @@ -2,9 +2,9 @@ This directory contains Cypress end-to-end tests for the Reminders application, ensuring the reliability and functionality of critical components. -## ⚠️ CI Environment Notice +## Continuous Integration -**Important**: Due to network restrictions in the CI environment, Cypress binary cannot be downloaded from `download.cypress.io`. The tests are configured to run using the official Cypress GitHub Action (`cypress-io/github-action@v6`) which handles the Cypress installation in CI environments. For local development, you can install and run Cypress normally. +CI runs use the official [`cypress-io/github-action`](https://github.com/cypress-io/github-action), which installs and caches the Cypress binary automatically. For local development, install and run Cypress normally via `npm install` and the scripts below. ## Overview @@ -41,7 +41,7 @@ src/test/cypress/ Before running Cypress tests, ensure the following: -1. **React Application**: The ReactJS Reminders app must be deployed to GitHub Pages at `https://kaueereinbold.github.io/Reminders` (for production tests) or running locally at `http://localhost:3000` (for development) +1. **React Application**: The ReactJS Reminders app must be deployed to GitHub Pages at `https://jumperck.github.io/Reminders` (for production tests) or running locally at `http://localhost:3000` (for development) 2. **API Backend**: The API should be available at `http://localhost:5000` (configured in cypress.config.js) 3. **Node.js**: Node.js version 16 or higher @@ -166,7 +166,7 @@ The test suite includes custom Cypress commands for common operations: Key configuration options in `cypress.config.js`: -- `baseUrl`: React app URL (default: `https://kaueereinbold.github.io/Reminders` for production, can be overridden with `CYPRESS_baseUrl` environment variable) +- `baseUrl`: React app URL (default: `https://jumperck.github.io/Reminders` for production, can be overridden with `CYPRESS_baseUrl` environment variable) - `env.apiUrl`: API backend URL (default: `http://localhost:5000`) - `viewportWidth/Height`: Test viewport dimensions - `video`: Enable/disable video recording @@ -205,7 +205,7 @@ Test fixtures in `cypress/fixtures/` provide: Cypress tests run automatically on pull requests and pushes to main against the deployed GitHub Pages application: 1. **GitHub Pages Deployment**: The React app is automatically deployed to GitHub Pages when changes are pushed to main -2. **Automatic Testing**: Cypress tests run against the deployed application at `https://kaueereinbold.github.io/Reminders` +2. **Automatic Testing**: Cypress tests run against the deployed application at `https://jumperck.github.io/Reminders` 3. **Test Results**: Screenshots and videos are collected as artifacts on test failures ### Local Development Testing From 102ef997586ac78492690d69daad6d688fca1bd9 Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:33:58 -0300 Subject: [PATCH 5/8] docs(agents): fix Go layout/namespaces/health, remove local path agents.md hardcoded a personal absolute path (/home/kaue/repos/...) in the quick-start snippet and in the Resources section, including a link to a specs repository that is not part of this repository; replaced with a git clone + relative-path flow. copilot-instructions.md described the Go API's internal layout as internal/handlers| repository|models, which does not exist - the real layout (verified in cmd/app/main.go) is cmd/app/ + pkg/api/ + pkg/models/. Both guides undercounted the load-balanced API instances as two (.NET + Go) when Nginx actually balances three (.NET, Go, and C++, verified in infrastructure/nginx.conf). The migration runner's /healthz:8081 and the Go API's /health were two genuinely different endpoints that read as conflicting at a glance; both docs now say so explicitly. Both guides also printed the Ganache test private key inline; replaced with a placeholder pointing at .env.example. --- .github/copilot-instructions.md | 40 ++++++++++++++++----------------- agents.md | 40 +++++++++++++++++---------------- 2 files changed, 41 insertions(+), 39 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 05e8c918..4f067cff 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,10 +2,10 @@ ## Architecture Overview -This is a **full-stack learning project** for managing reminders with multiple client interfaces (React, ASP.NET MVC), a load-balanced .NET API, and blockchain integration. +This is a **full-stack learning project** for managing reminders with multiple client interfaces (React, ASP.NET MVC), three load-balanced API backends (.NET, Go, C++), and blockchain integration. ### Tech Stack -- **Backend**: ASP.NET Core 8.0 Web API + Go Gin API (2 instances behind Nginx load balancer) +- **Backend**: ASP.NET Core 8.0 Web API + Go (Gin) API + C++ API (3 instances behind Nginx load balancer) - **Frontend**: Next.js 15 (React 19) + ASP.NET MVC - **Database**: PostgreSQL (primary) or SQL Server (legacy support) - **Blockchain**: Hardhat + Solidity smart contracts on Ganache @@ -28,18 +28,17 @@ src/ │ │ │ │ │ └── SqlServer/Migrations/ # SQL Server migrations (legacy) │ │ │ │ └── CrossCutting/ # Shared infrastructure │ │ │ └── Extensions/ # Middleware & DI extensions -│ │ └── go/reminders-api/ # Go (Gin) API - lightweight implementation -│ │ ├── cmd/app/ # Application entry point -│ │ ├── internal/ # Internal packages -│ │ │ ├── handlers/ # HTTP handlers -│ │ │ ├── repository/ # Data access -│ │ │ └── models/ # Domain models -│ │ └── wait-for-dotnet.sh # Startup helper script +│ │ ├── go/reminders-api/ # Go (Gin) API - lightweight implementation +│ │ │ ├── cmd/app/ # Application entry point (main.go) +│ │ │ ├── pkg/api/ # HTTP handlers + repository (Postgres) +│ │ │ ├── pkg/models/ # Domain models +│ │ │ └── wait-for-dotnet.sh # Startup helper script +│ │ └── cpp/reminders-api/ # C++ API - third load-balanced instance ├── app/ │ ├── reactjs/reminders-app/ # Next.js App Router app │ └── dotnet/Reminders.Mvc/ # ASP.NET MVC app -blockchain/ # Hardhat smart contracts -test/cypress/ # E2E tests +└── test/cypress/ # E2E tests +blockchain/ # Hardhat smart contracts (repo root, alongside src/) ``` ## Critical Workflows @@ -70,7 +69,7 @@ docker compose --profile production -f docker-compose.yml -f docker-compose.prod **Architecture**: - **Execution Model**: Runs once per deployment, exits after completion (not long-running) - **Orchestration**: Docker Compose ensures `migrations` service completes successfully before starting `dotnet-api` and `go-api` -- **Health Endpoint**: Exposes `/healthz` on port 8081 (development only) +- **Health Endpoint**: Exposes `GET /healthz` on port 8081 (development only) - this is the migration runner's own health check, distinct from the Go API's `GET /health` described under "Go API Specifics" below - HTTP 500: Migrations pending, running, or failed - HTTP 200: Migrations completed successfully - **Retry Logic**: Exponential backoff with jitter (5 attempts, 2s base delay) @@ -125,12 +124,12 @@ cd src/app/reactjs/reminders-app && npm test cd blockchain && npm test # Run Cypress E2E tests -cd test/cypress && npm run cy:run +cd src/test/cypress && npm run cy:run # Run .NET API tests (requires running API) -docker compose up postgres ganache -d +docker compose --profile api up postgres ganache -d cd src/server/api/dotnet/Reminders.Api && dotnet run & -cd test/server/dotnet/Reminders.Api.Test && dotnet test +cd src/test/server/dotnet/Reminders.Api.Test && dotnet test ``` ### Blockchain Development @@ -195,7 +194,7 @@ Uses **Next.js App Router** with: DATABASE_PROVIDER=Postgres CONNECTION_STRING=Host=reminders-postgres;Database=Reminders;Username=postgres;Password=YOUR_PASSWORD_HERE BLOCKCHAIN_NODE_URL=http://reminders-blockchain:8545 -BLOCKCHAIN_PRIVATE_KEY=0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3 +BLOCKCHAIN_PRIVATE_KEY= CORS_ORIGINS=http://localhost:3000 API_BASE_URL=http://reminders-nginx:9999 ``` @@ -203,19 +202,20 @@ API_BASE_URL=http://reminders-nginx:9999 ## Integration Points ### Load Balancing -Two API instances (`dotnet-api` running .NET, `go-api` running Go) behind Nginx ([infrastructure/nginx.conf](../infrastructure/nginx.conf)). Requests to port 9999 are load-balanced round-robin between both backends. +Three API instances (`dotnet-api`, `go-api`, `cpp-api`) behind Nginx ([infrastructure/nginx.conf](../infrastructure/nginx.conf)). Requests to port 9999 are load-balanced round-robin across all three backends. **Architecture Notes**: -- Both APIs implement the same REST endpoints for reminders CRUD +- All three APIs implement the same REST endpoints for reminders CRUD - .NET API: Layered architecture with full blockchain integration - Go API: Lightweight Gin-based implementation, shares same PostgreSQL database -- Both APIs add `X-Server` header to responses (`dotnet` or `go`) for identification +- C++ API: Third load-balanced instance, shares the same PostgreSQL database +- All three APIs add an `X-Server` response header for identification **Go API Specifics**: - Uses Gin web framework - Repository pattern with direct PostgreSQL access - Environment: `PostgresDefaultConnection` connection string -- Healthcheck: `GET /health` returns `"Healthy"` +- Healthcheck: `GET /health` returns `"Healthy"` (container port 8080, published as host port 5001 via Docker Compose) - No blockchain integration (API-only service) See [src/server/api/go/reminders-api/README.md](../src/server/api/go/reminders-api/README.md) for details. diff --git a/agents.md b/agents.md index 1a38e4ac..b0b4ddbc 100644 --- a/agents.md +++ b/agents.md @@ -8,9 +8,7 @@ A full-stack learning project for managing reminders with multiple client interfaces, load-balanced APIs, and blockchain integration. -**Tech Stack**: .NET 8.0, Go (Gin), Next.js 15, PostgreSQL, Solidity, Docker Compose - -**Repository**: Multi-workspace (specs + application) +**Tech Stack**: .NET 8.0, Go (Gin), C++, Next.js 15, PostgreSQL, Solidity, Docker Compose ## Quick Start for Agents @@ -18,7 +16,8 @@ A full-stack learning project for managing reminders with multiple client interf ```bash # Clone and setup -cd /home/kaue/repos/reminders/Reminders +git clone https://github.com/jumperck/Reminders.git +cd Reminders cp .env.example .env # Start all services @@ -32,6 +31,7 @@ docker compose logs -f dotnet-api go-api migrations - **API (.NET)**: `src/server/api/dotnet/Reminders.Api/` - **API (Go)**: `src/server/api/go/reminders-api/` +- **API (C++)**: `src/server/api/cpp/reminders-api/` - **Migration Runner**: `src/server/services/dotnet/Reminders.MigrationsRunner/` - **React Frontend**: `src/app/reactjs/reminders-app/` - **Smart Contracts**: `blockchain/contracts/Reminders.sol` @@ -87,19 +87,20 @@ dotnet ef migrations add MigrationName \ **Important Notes**: - Migration runner has retry logic (5 attempts, exponential backoff) -- Health endpoint at `/healthz:8081` (dev only) +- Migration runner health endpoint: `GET /healthz` on port 8081 (dev only) - distinct from the Go API's own `GET /health` on port 8080/5001, see below - Provider-specific migrations applied automatically - Expected: SQL Server migration errors when using PostgreSQL (harmless) ### Load Balancing -Two backend instances behind Nginx: +Three backend instances behind Nginx: - **dotnet-api**: .NET Core with full blockchain integration - **go-api**: Lightweight Go (Gin) implementation +- **cpp-api**: C++ implementation -Both share the same PostgreSQL database. Load balanced round-robin on port 9999. +All three share the same PostgreSQL database. Load balanced round-robin on port 9999. -**Server Identification**: Check `X-Server` response header (`dotnet` or `go`) +**Server Identification**: Check `X-Server` response header (`dotnet`, `go`, or `cpp`) ## Coding Standards @@ -193,7 +194,8 @@ export default function EditClient() { - **Repository Pattern**: Direct PostgreSQL access - **Error Handling**: Gin's built-in error handling - **Server Header**: Always add `X-Server: go` header -- **Health Endpoint**: `GET /health` returns `"Healthy"` +- **Health Endpoint**: `GET /health` returns `"Healthy"` (container port 8080, published as host port 5001 via Docker Compose) +- **Layout**: `cmd/app/main.go` (entry point), `pkg/api/` (handlers + repository), `pkg/models/` (domain models) ## Environment Configuration @@ -206,8 +208,9 @@ CONNECTION_STRING=Host=reminders-postgres;Database=Reminders;Username=postgres;P # Blockchain BLOCKCHAIN_NODE_URL=http://reminders-blockchain:8545 -BLOCKCHAIN_PRIVATE_KEY=0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3 -BLOCKCHAIN_CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3 +BLOCKCHAIN_PRIVATE_KEY= +BLOCKCHAIN_CONTRACT_ADDRESS= +# See .env.example for the actual local development values (Ganache test keys only) # API CORS_ORIGINS=http://localhost:3000,http://localhost:5000 @@ -305,13 +308,13 @@ public async Task AddRangeAsync(IEnumerable reminders) ```bash # Start dependencies -docker compose up postgres ganache -d +docker compose --profile api up postgres ganache -d # Run API cd src/server/api/dotnet/Reminders.Api && dotnet run & # Run tests -cd test/server/dotnet/Reminders.Api.Test && dotnet test +cd src/test/server/dotnet/Reminders.Api.Test && dotnet test ``` ### React Tests @@ -334,7 +337,7 @@ npm test # Hardhat tests with Chai ### E2E Tests ```bash -cd test/cypress +cd src/test/cypress npm install npm run cy:open # Interactive mode npm run cy:run # Headless mode @@ -447,7 +450,7 @@ foreach (var reminder in reminders) **Solutions**: 1. Check both API instances are healthy: `docker compose ps dotnet-api go-api` -2. Test each API directly: `curl http://localhost:8080/health` (bypasses Nginx) +2. Test each API directly, bypassing Nginx: `curl http://localhost:5000/health` (.NET), `curl http://localhost:5001/health` (Go) 3. Review Nginx config: `infrastructure/nginx.conf` 4. Check Nginx logs: `docker compose logs nginx` @@ -488,10 +491,9 @@ foreach (var reminder in reminders) ## Resources -- **Project README**: `/home/kaue/repos/reminders/Reminders/README.md` -- **Contributing Guide**: `/home/kaue/repos/reminders/Reminders/CONTRIBUTING.md` -- **Specs Repository**: `/home/kaue/repos/reminders/reminders-specs/specs/` -- **API Documentation**: `http://localhost:8080/swagger` (when running) +- **Project README**: [`README.md`](README.md) +- **Contributing Guide**: [`CONTRIBUTING.md`](CONTRIBUTING.md) +- **API Documentation**: `http://localhost:5000/swagger` (when running .NET API via Docker Compose) - **Blockchain Explorer**: `http://localhost:8545` (Ganache) ## Contact & Support From 79751f8375ccb2f4ff272f91220f0190b3a131ea Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:50:48 -0300 Subject: [PATCH 6/8] docs(readme): trim to lean front-door, drop duplicate usage --- README.md | 359 +----------------------------------------------------- 1 file changed, 5 insertions(+), 354 deletions(-) diff --git a/README.md b/README.md index 84ad3382..7d920297 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ A simple and intuitive web application for managing your daily reminders. ## Features -- **User-friendly Interface**: Easily create, edit, and delete reminders with a clean and intuitive user interface. +- **User-friendly Interface**: Easily create, edit, and delete reminders with a clean and intuitive UI. - **Persistent Storage**: Reminders are stored securely, ensuring you never lose your important tasks. - **Customization**: Customize your reminders with different colors, tags, and priority levels. - **Reminders Notification**: Receive timely reminders to stay on top of your tasks. ## Learning Project -Please note that as a learning project, the code here may not follow best practices at all times as it's a process of learning and improving. Feedback and suggestions are always welcome! +As a learning project, the code here may not follow best practices at all times as it's a process of learning and improving. Feedback and suggestions are always welcome! ## Prerequisites @@ -74,8 +74,6 @@ Once all containers are running: - **Go API**: [http://localhost:5001](http://localhost:5001) - **C++ API**: [http://localhost:5002](http://localhost:5002) -### Verify Everything is Running - ```bash # Check container status docker compose ps @@ -125,358 +123,11 @@ Reminders API: ## Testing -The Reminders application includes comprehensive testing to ensure reliability and functionality: - -### Unit Testing with Jest - -The ReactJS application includes unit tests using Jest and React Testing Library: - -- **Location**: `src/app/reactjs/reminders-app/src/` -- **Coverage**: Components, hooks, API layers, and pages -- **Status**: ✅ All tests passing (99.6% coverage) -- **Run tests**: `npm test` (in the React app directory) -- **Coverage report**: `npm test -- --coverage` - -### Blockchain Testing with Hardhat - -Smart contract tests using Hardhat and Chai: - -- **Location**: `blockchain/test/` -- **Coverage**: Lock and Reminders contracts -- **Status**: ✅ All tests passing (10 tests) -- **Run tests**: `npm test` (in the blockchain directory) - -### Quick Test All - -Run the automated test suite: - -```bash -# Run all available tests -./run-tests.sh -``` - -This will run: - -- ✅ React/Jest unit tests (61 tests) -- ✅ Blockchain/Hardhat tests (10 tests) -- ⚠️ .NET integration tests (if API is running) - -### End-to-End Testing with Cypress - -Comprehensive E2E tests validate critical user interactions against the deployed application: - -- **Location**: `src/test/cypress/` -- **Testing Environment**: Tests run against the deployed GitHub Pages application at `https://jumperck.github.io/Reminders` -- **Coverage**: List, Create, Edit, Delete operations -- **Test categories**: - - List functionality (viewing reminders) - - Creation workflow (create new reminder) - - Editing workflow (modify existing reminder) - - Deletion workflow (remove reminder with confirmation) - - Integration tests (full user journeys) -- **Run tests**: - - Interactive: `npm run cy:open` (in Cypress directory) - - Headless: `npm run cy:run` (in Cypress directory) - - Against local dev: `CYPRESS_baseUrl=http://localhost:3000 npm run cy:run` - -For detailed testing setup and usage instructions, see: - -- [Cypress Testing README](src/test/cypress/README.md) - -### .NET Integration Tests - -**Note**: Integration tests require the API to be running on `http://localhost:5000`. - -**To run integration tests:** - -```bash -# 1. Start the API and database -docker compose --profile api up postgres ganache -d -cd src/server/api/dotnet/Reminders.Api -dotnet run - -# 2. In a new terminal, run the tests -cd src/test/server/dotnet/Reminders.Api.Test -dotnet test -``` - -**Selenium Tests**: The MVC Selenium tests require Chrome/Firefox drivers and browsers installed. These are primarily for local development and may be skipped in CI environments. - -### Continuous Integration - -All tests run automatically on pull requests: - -- Jest unit tests via GitHub Actions -- Cypress E2E tests via GitHub Actions -- Coverage reporting and artifact collection - -## Docker Compose Configuration - -This section describes the Docker Compose configuration for deploying the Reminders application. - -### Database Migrations - -The Reminders application uses a **dedicated migration runner service** to manage database schema updates. This design decouples migration execution from API startup, providing better reliability and orchestration. - -#### Migration Runner Service - -- **Purpose**: Applies Entity Framework Core migrations before API instances start -- **Technology**: .NET 8.0 console application with embedded HTTP health endpoint -- **Execution**: Runs once per deployment, exits after completion (not a long-running service) -- **Health Endpoint**: `http://localhost:8081/healthz` (exposed in development mode only) -- **Location**: `src/server/services/dotnet/Reminders.MigrationsRunner/` - -#### How It Works - -1. **Database Ready**: PostgreSQL container starts and reports healthy via healthcheck -2. **Migrations Run**: Migration runner service starts, applies all pending migrations with retry logic (exponential backoff, 5 attempts) -3. **Health Check**: Runner exposes HTTP 500 while running, HTTP 200 on success -4. **APIs Start**: Once migration runner exits successfully (code 0), both API instances start simultaneously -5. **Production Ready**: APIs are guaranteed to have correct schema before handling requests - -#### Docker Compose Orchestration - -```yaml -services: - migrations: - depends_on: - postgres: - condition: service_healthy - restart: "no" # Run once, do not restart - - dotnet-api: - depends_on: - migrations: - condition: service_completed_successfully -``` - -#### Running Migrations Manually - -**Local Development** (without Docker): - -```bash -# Navigate to migration runner directory -cd src/server/services/dotnet/Reminders.MigrationsRunner - -# Configure connection in appsettings.json or via environment -export ConnectionStrings__DefaultConnection="Host=localhost;Database=Reminders;Username=postgres;Password=yourpassword" -export DatabaseProvider="Postgres" - -# Run migrations -dotnet run - -# Check health endpoint (in another terminal) -curl http://localhost:8081/healthz -``` - -**Docker Compose** (recommended): - -```bash -# Full stack with migrations -docker compose --profile all up -d - -# Check migration runner logs -docker compose logs migrations - -# Verify migration completed successfully -docker compose ps migrations -# Should show "Exited (0)" status -``` - -**Creating New Migrations**: - -```bash -# From repository root -cd src/server/api/dotnet/Reminders.Api - -# Create new migration for PostgreSQL -dotnet ef migrations add YourMigrationName \ - --context RemindersContext \ - --output-dir Layers/Data/EntityFramework/Postgres/Migrations - -# Or for SQL Server (legacy) -dotnet ef migrations add YourMigrationName \ - --context RemindersContext \ - --output-dir Layers/Data/EntityFramework/SqlServer/Migrations -``` - -#### Configuration - -Migration runner settings in `appsettings.json`: - -```json -{ - "ConnectionStrings": { - "DefaultConnection": "Host=postgres;Database=Reminders;..." - }, - "DatabaseProvider": "Postgres", - "MigrationRunner": { - "MaxRetryAttempts": 5, - "RetryBaseDelaySeconds": 2 - } -} -``` - -Environment variables override (Docker): - -```bash -ConnectionStrings__DefaultConnection="..." -DatabaseProvider="Postgres" -MigrationRunner__MaxRetryAttempts=5 -MigrationRunner__RetryBaseDelaySeconds=2 -``` - -#### Troubleshooting Migrations - -**Migration Runner Fails to Start**: - -```bash -# Check logs -docker compose logs migrations - -# Common causes: -# - Database not ready (wait for postgres healthcheck) -# - Invalid connection string -# - Missing environment variables -``` - -**Migrations Fail to Apply**: - -```bash -# Check detailed error in logs -docker compose logs migrations - -# Manually test connection -docker compose exec postgres psql -U root -d Reminders -c "\dt" - -# Reset database (caution: deletes all data) -docker compose down -v -docker compose --profile all up -d -``` - -**API Won't Start After Migration Failure**: - -The migration runner must exit with code 0 for APIs to start. Check: - -```bash -# Migration runner exit code -docker compose ps migrations - -# If exit code is 1, fix the issue and restart -docker compose up migrations -d --force-recreate -``` - -**Multiple Providers Warning**: - -When using PostgreSQL (default), you may see SQL Server migration errors in logs. This is **expected and harmless** — the migration runner applies only the provider-specific migrations. - -### Local dev — Compose healthcheck & migrations - -- The `postgres` service includes a `healthcheck` to report when the database is ready -- The `migrations` service depends on `postgres` with `condition: service_healthy` and runs database migrations before APIs start -- API services (`dotnet-api`, `go-api`) depend on `migrations` with `condition: service_completed_successfully`, ensuring they only start after successful migration -- The migration runner uses retry logic with exponential backoff (5 attempts, 2s base) to handle transient connection issues -- Runtime configuration for the migration runner is available in `appsettings.json` or via environment variables - -To bring up only the API stack (useful for local dev): - -```bash -# start postgres, migrations, ganache and api-related services -docker compose --profile api up -d --build - -# verify postgres health -docker ps --filter name=reminders-postgres --format "{{.Names}}\t{{.Status}}" - -# check migration runner completed -docker ps --filter name=reminders-migrations-runner --format "{{.Names}}\t{{.Status}}" - -# check API health (after migrations complete) -curl -i http://localhost:5000/health -``` - - -## Usage - -To deploy the Reminders application using Docker Compose, follow these steps: - -1. Clone the repository: `git clone https://github.com/jumperck/Reminders.git` -2. Navigate to the project directory: `cd Reminders` -3. Run Docker Compose: `docker compose up -d` - -The application can be accessed using the following URLs: - -- **API 1:** [http://localhost:5000](http://localhost:5000) -- **API 2:** [http://localhost:5001](http://localhost:5001) -- **MVC:** [http://localhost:5050](http://localhost:5050) -- **Nginx Load Balancer:** [http://localhost:9999](http://localhost:9999) - -Please note that the exact URLs may vary based on your specific configuration and environment. Adjust them accordingly. - -## Troubleshooting - -### Common Issues - -#### Database Migration Warning Message - -**Symptom**: When starting the API, you see an error about failed SQL Server migration. - -**Cause**: The project supports both PostgreSQL and SQL Server. When using PostgreSQL (default), the SQL Server migration will fail. - -**Solution**: This is **expected behavior** and harmless. The PostgreSQL migration succeeds, and you can safely ignore the SQL Server migration error. The application will run normally. - -#### Ports Already in Use - -**Symptom**: Docker Compose fails with "port is already allocated" error. - -**Solution**: - -```bash -# Check what's using the port (example for port 5432) -lsof -ti:5432 | xargs kill -9 - -# Or stop all containers and try again -docker compose down -docker compose --profile all up -d -``` - -#### Docker Build Takes Too Long - -**Symptom**: Initial build takes 10+ minutes. - -**Solution**: This is normal for the first build. Docker needs to: - -- Download base images (.NET, Node.js, PostgreSQL, Nginx, Ganache) -- Install all dependencies -- Build all services - -Subsequent builds will be much faster thanks to Docker's layer caching. - -#### Cannot Connect to Database - -**Symptom**: API fails to start with database connection errors. - -**Solution**: - -1. Ensure PostgreSQL is running: `docker compose ps` -2. Check your `.env` file has correct password -3. Verify the database container is healthy: `docker logs reminders-postgres` -4. Wait a few seconds for PostgreSQL to fully initialize - -#### React App Shows API Connection Error - -**Symptom**: Frontend can't connect to the API. - -**Solution**: - -1. Ensure API is running: `curl http://localhost:9999/health` -2. Check CORS configuration in your `.env` file -3. Verify Nginx is running: `docker compose ps reminders-nginx` +The project has unit tests (React/Jest), smart contract tests (Hardhat), .NET integration tests, and end-to-end tests (Cypress) covering the core reminder workflows. Run `./run-tests.sh` from the repository root for the automated suite, or see [CONTRIBUTING.md](CONTRIBUTING.md#testing) and the [Cypress Testing README](src/test/cypress/README.md) for how to run each suite individually. -### Getting Help +Migrations are applied by a dedicated runner service before the APIs start - see [CONTRIBUTING.md](CONTRIBUTING.md#database-migrations) for how that works and how to troubleshoot it. -- Check [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines -- Check the [Issues](https://github.com/jumperck/Reminders/issues) page for known problems -- Open a new issue if you encounter a bug +See [CONTRIBUTING.md](CONTRIBUTING.md) for general troubleshooting (ports in use, database connection issues, slow first build). ## Contributing From 0be877a3406bef514cb6c11db0318b2d654bcdbd Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 07:50:48 -0300 Subject: [PATCH 7/8] docs(contributing): consolidate migration and troubleshooting guidance --- CONTRIBUTING.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 80 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fad6748..2349ba93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,6 +96,64 @@ The project supports both **PostgreSQL** (default) and **SQL Server**. Migration Migrations are applied by a **dedicated migration runner service** (`src/server/services/dotnet/Reminders.MigrationsRunner/`), not by the API itself. Docker Compose starts `postgres`, waits for it to report healthy, then runs `migrations` to completion before either API instance starts. When PostgreSQL is the active provider (default), the runner also attempts the SQL Server migration set and logs an expected failure for it - **this is expected and harmless**. Only the PostgreSQL migrations are actually applied. +### How the Runner Works + +- **Technology**: .NET 8.0 console app with an embedded HTTP health endpoint (`http://localhost:8081/healthz`, development mode only). Runs once per deployment and exits, it is not a long-running service. +- **Order**: `postgres` starts and reports healthy, then `migrations` runs with retry logic (exponential backoff, 5 attempts, 2s base delay), and once it exits with code 0 both `dotnet-api` and `go-api` start (each depends on `migrations` with `condition: service_completed_successfully`). +- **Health signal**: the runner exposes HTTP 500 while running and HTTP 200 once migrations succeed. + +### Running Migrations Manually + +**Local development (without Docker):** + +```bash +cd src/server/services/dotnet/Reminders.MigrationsRunner + +export ConnectionStrings__DefaultConnection="Host=localhost;Database=Reminders;Username=postgres;Password=yourpassword" +export DatabaseProvider="Postgres" + +dotnet run + +# check health endpoint in another terminal +curl http://localhost:8081/healthz +``` + +**Via Docker Compose (recommended):** + +```bash +docker compose --profile all up -d + +# check migration runner logs +docker compose logs migrations + +# verify it completed successfully - should show "Exited (0)" +docker compose ps migrations +``` + +### Runner Configuration + +Settings live in `appsettings.json`, or override via environment variables: + +```json +{ + "ConnectionStrings": { + "DefaultConnection": "Host=postgres;Database=Reminders;..." + }, + "DatabaseProvider": "Postgres", + "MigrationRunner": { + "MaxRetryAttempts": 5, + "RetryBaseDelaySeconds": 2 + } +} +``` + +```bash +ConnectionStrings__DefaultConnection="..." +DatabaseProvider="Postgres" +MigrationRunner__MaxRetryAttempts=5 +MigrationRunner__RetryBaseDelaySeconds=2 +``` + ### Creating New Migrations Always specify the context and output directory: @@ -118,6 +176,12 @@ dotnet ef migrations add MigrationName \ --output-dir Layers/Data/EntityFramework/SqlServer/Migrations ``` +### Troubleshooting Migrations + +- **Runner fails to start**: check `docker compose logs migrations`. Usual causes are the database not being ready yet, an invalid connection string, or missing environment variables. +- **Migrations fail to apply**: check the logs for the detailed error, then test the connection directly with `docker compose exec postgres psql -U root -d Reminders -c "\dt"`. As a last resort, `docker compose down -v && docker compose --profile all up -d` resets the database (this deletes all data). +- **API won't start after a migration failure**: the runner must exit with code 0 for the APIs to start. Check `docker compose ps migrations`; if the exit code is non-zero, fix the underlying issue and run `docker compose up migrations -d --force-recreate`. + ## Making Changes ### Branching Strategy @@ -251,11 +315,17 @@ npm run dev #### Port Already in Use ```bash -# Find and kill process using port 5000 +# Find and kill process using a port (example: 5000) lsof -ti:5000 | xargs kill -9 + +# Or stop all containers and try again +docker compose down +docker compose --profile all up -d ``` -#### Docker Build Fails +#### Docker Build Fails or Takes Too Long + +The first build can take 10+ minutes since Docker has to download base images (.NET, Node.js, PostgreSQL, Nginx, Ganache) and install all dependencies. Subsequent builds are much faster thanks to layer caching. If a build is actually failing: ```bash # Clean Docker cache @@ -265,9 +335,15 @@ docker compose down -v #### Database Connection Issues -- Ensure PostgreSQL container is running: `docker compose ps` +- Ensure PostgreSQL container is running and healthy: `docker compose ps` / `docker logs reminders-postgres` - Check `.env` file has correct credentials -- Verify port 5432 is not blocked +- Verify port 5432 is not blocked, and give PostgreSQL a few seconds to finish initializing + +#### React App Shows API Connection Error + +- Ensure the API is reachable: `curl http://localhost:9999/health` +- Check CORS configuration in your `.env` file +- Verify Nginx is running: `docker compose ps reminders-nginx` ## Questions or Need Help? From 5ddbd2c738121c989c61f4716054e12dd6d9cde4 Mon Sep 17 00:00:00 2001 From: Kaue Reinbold Date: Fri, 10 Jul 2026 08:03:35 -0300 Subject: [PATCH 8/8] ci: skip build workflows on markdown-only changes --- .github/workflows/blockchain-pull-request.yml | 1 + .github/workflows/cypress-e2e.yml | 1 + .github/workflows/deploy-pages.yml | 1 + .github/workflows/dotnet-code-coverage.yml | 1 + .github/workflows/dotnet-pull-request.yml | 1 + .github/workflows/go-pull-request.yml | 1 + .github/workflows/react-pull-request.yml | 1 + 7 files changed, 7 insertions(+) diff --git a/.github/workflows/blockchain-pull-request.yml b/.github/workflows/blockchain-pull-request.yml index 68666c00..9dbbf3bd 100644 --- a/.github/workflows/blockchain-pull-request.yml +++ b/.github/workflows/blockchain-pull-request.yml @@ -8,6 +8,7 @@ on: - main paths: - 'blockchain/**' + - '!blockchain/**/*.md' permissions: contents: read diff --git a/.github/workflows/cypress-e2e.yml b/.github/workflows/cypress-e2e.yml index c7e776f6..df3471b6 100644 --- a/.github/workflows/cypress-e2e.yml +++ b/.github/workflows/cypress-e2e.yml @@ -18,6 +18,7 @@ on: - main paths: - 'src/test/cypress/**' + - '!src/test/cypress/**/*.md' # Allow manual trigger for debugging workflow_dispatch: diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 719ce2d8..ac851dc6 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -8,6 +8,7 @@ on: - main paths: - 'src/app/reactjs/reminders-app/**' + - '!src/app/reactjs/reminders-app/**/*.md' workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages diff --git a/.github/workflows/dotnet-code-coverage.yml b/.github/workflows/dotnet-code-coverage.yml index 4a147d99..262271dd 100644 --- a/.github/workflows/dotnet-code-coverage.yml +++ b/.github/workflows/dotnet-code-coverage.yml @@ -11,6 +11,7 @@ on: - 'src/app/dotnet/**' - 'src/server/services/dotnet/**' - 'src/test/server/dotnet/**' + - '!**/*.md' permissions: contents: read diff --git a/.github/workflows/dotnet-pull-request.yml b/.github/workflows/dotnet-pull-request.yml index b3759dd5..5a553006 100644 --- a/.github/workflows/dotnet-pull-request.yml +++ b/.github/workflows/dotnet-pull-request.yml @@ -11,6 +11,7 @@ on: - 'src/app/dotnet/**' - 'src/server/services/dotnet/**' - 'src/test/server/dotnet/**' + - '!**/*.md' permissions: contents: read diff --git a/.github/workflows/go-pull-request.yml b/.github/workflows/go-pull-request.yml index 992057c4..b1a59b34 100644 --- a/.github/workflows/go-pull-request.yml +++ b/.github/workflows/go-pull-request.yml @@ -8,6 +8,7 @@ on: - main paths: - 'src/server/api/go/reminders-api/**' + - '!src/server/api/go/reminders-api/**/*.md' permissions: contents: read diff --git a/.github/workflows/react-pull-request.yml b/.github/workflows/react-pull-request.yml index 5b8cc7fd..067155ae 100644 --- a/.github/workflows/react-pull-request.yml +++ b/.github/workflows/react-pull-request.yml @@ -8,6 +8,7 @@ on: - main paths: - 'src/app/reactjs/reminders-app/**' + - '!src/app/reactjs/reminders-app/**/*.md' permissions: contents: read