From abc5fb4cb3c5089fd0f2b9f6c87c82098b2f3782 Mon Sep 17 00:00:00 2001 From: Ricardo Campos Date: Wed, 27 Aug 2025 11:13:56 -0300 Subject: [PATCH] fix: json error and docs (#630) * feat: add docs and reflection solution - wip * fix: login and jjwt cloud native issue --- CLAUDE.md | 101 +++++++ README.md | 284 ++++++++++++++++-- server/pom.xml | 8 +- .../META-INF/native-image/reflect-config.json | 53 +++- 4 files changed, 422 insertions(+), 24 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..92f9c5d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,101 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Commands + +### Frontend (React/TypeScript) +```bash +cd client +npm start # Start development server on port 5000 +npm run build # Build production bundle (TypeScript compilation + Vite build) +npm run preview # Preview production build +npm test # Run Vitest tests +npm run test:coverage # Run tests with coverage report +npm run lint # Run ESLint +npm run lint:fix # Run ESLint with auto-fix +``` + +### Backend (Java/Spring Boot) +```bash +cd server +./mvnw spring-boot:run # Start development server +./mvnw clean compile # Compile Java sources +./mvnw test # Run unit tests only +./mvnw clean verify -Ptests # Run all tests (unit + integration) with coverage +./mvnw spring-boot:build-image # Build Docker image +./mvnw clean verify -Pnative # Build GraalVM native image +``` + +### Docker Development Environment +```bash +bash tools/run-docker-db.sh # Start PostgreSQL database +bash tools/run-docker-server.sh # Start backend in Docker +bash tools/run-docker-client.sh # Start frontend in Docker +bash tools/check-frontend.sh # Run frontend quality checks +bash tools/check-backend.sh # Run backend quality checks +``` + +## Architecture + +### Monorepo Structure +- `client/` - React TypeScript frontend (Vite + Vitest) +- `server/` - Java Spring Boot REST API +- `angular/` - Alternative Angular frontend (separate implementation) +- `tools/` - Development and deployment scripts +- `docker-compose.yml` - Multi-service development environment + +### Frontend Architecture (client/) +- **State Management**: React Context API for authentication and sidebar state +- **Authentication**: JWT tokens stored in localStorage with automatic refresh (2-minute intervals) +- **Routing**: Dynamic router configuration based on auth status (signed vs not-signed routes) +- **Internationalization**: i18next with support for English, Portuguese, Russian, Spanish +- **Styling**: Bootstrap 5 + SCSS with dark/light theme support +- **Testing**: Vitest with React Testing Library and coverage reporting +- **API Layer**: Centralized API service in `src/api-service/api.ts` with automatic auth headers + +### Backend Architecture (server/) +- **Framework**: Spring Boot 3.5+ with Java 17 +- **Security**: Spring Security with JWT authentication +- **Database**: PostgreSQL with JPA/Hibernate and Flyway migrations +- **Testing**: Separate unit tests and integration tests with 75% coverage requirement +- **Documentation**: OpenAPI/Swagger UI available at `/swagger-ui.html` +- **Build Options**: Traditional JAR or GraalVM native image compilation + +### Key Components + +**Authentication Flow:** +1. User credentials โ†’ `/auth/sign-in` endpoint +2. Server responds with JWT token and user data +3. Token stored in localStorage, added to all API requests via Authorization header +4. Automatic token refresh every 2 minutes via `/rest/user-sessions/refresh` +5. Protected routes wrap authenticated pages, redirect on auth failure + +**Database Schema:** +- Core entities: Users, Tasks, Notes, Task URLs, Notes URLs +- User management with password reset functionality +- Task completion tracking and user statistics + +## Development Workflow + +1. Start database: `bash tools/run-docker-db.sh` +2. Start backend: `bash tools/run-docker-server.sh` or `cd server && ./mvnw spring-boot:run` +3. Start frontend: `bash tools/run-docker-client.sh` or `cd client && npm start` +4. Access app at http://localhost:5000 + +Always run quality checks before submitting changes: +- Frontend: `bash tools/check-frontend.sh` +- Backend: `bash tools/check-backend.sh` + +## Testing + +### Frontend Testing +- **Framework**: Vitest + React Testing Library +- **Coverage**: Generated in `client/coverage/` directory +- **Run**: `cd client && npm test` or `npm run test:coverage` + +### Backend Testing +- **Unit Tests**: Standard JUnit tests, run with `./mvnw test` +- **Integration Tests**: Files ending in `*IntTest.java`, require database +- **Coverage**: JaCoCo reports, 75% minimum requirement +- **Full Test Suite**: `./mvnw clean verify -Ptests` (includes checkstyle, coverage) \ No newline at end of file diff --git a/README.md b/README.md index 7037873..4dc0e91 100644 --- a/README.md +++ b/README.md @@ -22,43 +22,289 @@ - [๐Ÿ“ About the Project](#-about-the-project) - [โœจ Features](#-features) - [๐Ÿš€ Tech Stack](#-tech-stack) -- [๐Ÿ›  Contributing](#-contributing) +- [๐Ÿ—๏ธ Architecture](#๏ธ-architecture) +- [๐Ÿš€ Getting Started](#-getting-started) +- [๐Ÿ› ๏ธ Development](#๏ธ-development) +- [๐Ÿงช Testing](#-testing) +- [๐Ÿ“ฆ Deployment](#-deployment) +- [๐Ÿค Contributing](#-contributing) +- [๐Ÿ‘จโ€๐Ÿ’ป Developer](#-developer) - [๐Ÿ“ž Contact](#-contact) - [๐Ÿ“„ License](#-license) ## ๐Ÿ“ About the Project -TaskNote was firstly created to meet my personal needs of having a simple tool to manage tasks and notes. Clean and minimal. However after a couple of weeks I was assigned a challenge to finish within one month a set of tasks, technical tasks, that I decided to put it practice here, at this project. At the end of that month, I got most the app ready. +TaskNote is a full-stack productivity application designed for managing tasks and notes with simplicity and effectiveness in mind. Originally created to address personal productivity needs, it has evolved into a comprehensive, open-source solution featuring a modern tech stack and enterprise-grade architecture. -Then I decided keep going, found a host and a name. And that's it. Here we are! +The project was born from a month-long technical challenge and has since grown to include robust authentication, internationalization support, responsive design, and comprehensive testing coverage. ## โœจ Features -- Current features - - Create and manage TODO items - - Create and manage Notes - - Search by any matching text - - A key feature is that this tool is super simple, but effective. -- Upcoming features - - `#tag` a task or note - - Improved search filters +### Current Features +- **Task Management**: Create, edit, delete, and organize TODO items with due dates and priority levels +- **Note Taking**: Rich text notes with Markdown support for better formatting +- **Smart Search**: Full-text search across tasks and notes with real-time filtering +- **User Authentication**: Secure JWT-based authentication with automatic token refresh +- **Internationalization**: Multi-language support (English, Portuguese, Spanish, Russian) +- **Responsive Design**: Mobile-first approach with Bootstrap 5 and dark/light theme support +- **Data Visualization**: Task completion charts and productivity analytics +- **File Attachments**: URL attachments for tasks and notes + +### Upcoming Features +- **Tagging System**: `#tag` support for better organization +- **Advanced Filters**: Enhanced search with date ranges, priority levels, and status filters +- **Collaboration**: Share tasks and notes with other users +- **Mobile App**: Native mobile applications for iOS and Android +- **Notifications**: Email and push notifications for due dates and reminders ## ๐Ÿš€ Tech Stack -- **Frontend:** React, Typescript, Vite, Vitest, Code Coverage -- **Backend:** Java 17, Spring Web, GraalVM Cloud Native Image -- **Database:** PostgreSQL, Flyway -- **Other Technologies:** Docker, Docker Compose, Caddy +### Frontend (React TypeScript) +- **Framework**: React 19 with TypeScript for type safety +- **Build Tool**: Vite for fast development and optimized production builds +- **Testing**: Vitest with React Testing Library and comprehensive coverage reporting +- **Styling**: Bootstrap 5 with custom SCSS and theme support +- **State Management**: React Context API for authentication and sidebar state +- **Routing**: React Router 7 with dynamic route configuration +- **Internationalization**: i18next with automatic language detection +- **API Client**: Centralized API service with automatic authentication headers -## ๐Ÿ›  Contributing +### Backend (Java Spring Boot) +- **Framework**: Spring Boot 3.5+ with Java 17 +- **Security**: Spring Security with JWT authentication and refresh tokens +- **Database**: PostgreSQL with JPA/Hibernate ORM +- **Migration**: Flyway for database schema versioning +- **Documentation**: OpenAPI/Swagger UI for API documentation +- **Testing**: JUnit with separate unit and integration test suites +- **Code Quality**: Checkstyle, JaCoCo coverage (75% minimum), Maven Enforcer +- **Build Options**: Traditional JAR or GraalVM native image compilation -Please refer to the [CONTRIBUTING](CONTRIBUTING.md) file for more information about how to run this application from source, and/or how to contribute. +### Database & Infrastructure +- **Database**: PostgreSQL with optimized indexes and constraints +- **Containerization**: Docker and Docker Compose for development environment +- **Web Server**: Caddy for reverse proxy and SSL termination +- **CI/CD**: GitHub Actions with automated testing and quality gates +- **Code Analysis**: SonarCloud integration for security and maintainability +## ๐Ÿ—๏ธ Architecture + +### Monorepo Structure +``` +react-typescript-todolist/ +โ”œโ”€โ”€ client/ # React TypeScript frontend +โ”œโ”€โ”€ server/ # Java Spring Boot REST API +โ”œโ”€โ”€ angular/ # Alternative Angular frontend +โ”œโ”€โ”€ tools/ # Development and deployment scripts +โ”œโ”€โ”€ docker-compose.yml +โ””โ”€โ”€ CLAUDE.md # AI assistant instructions +``` + +### Frontend Architecture +- **Component Structure**: Modular components with TypeScript interfaces +- **Authentication Flow**: JWT tokens with 2-minute refresh intervals +- **Theme System**: CSS custom properties for dark/light mode switching +- **Responsive Layout**: Mobile-first design with sidebar navigation +- **Error Handling**: Centralized error boundary and user feedback + +### Backend Architecture +- **RESTful API**: Clean REST endpoints with proper HTTP status codes +- **Security Layer**: JWT validation, CORS configuration, and input validation +- **Service Layer**: Business logic separation with transaction management +- **Repository Pattern**: Data access abstraction with custom queries +- **Email Service**: Template-based email notifications for user actions + +## ๐Ÿš€ Getting Started + +### Prerequisites +- **Docker & Docker Compose** (recommended for easy setup) +- **Node.js 18+** and **npm** (for frontend development) +- **Java 17+** and **Maven 3.6+** (for backend development) +- **PostgreSQL 13+** (if running without Docker) + +### Quick Start with Docker +1. **Clone the repository** + ```bash + git clone https://github.com/ricardo-campos-org/react-typescript-todolist.git + cd react-typescript-todolist + ``` + +2. **Start the database** + ```bash + bash tools/run-docker-db.sh + ``` + +3. **Start the backend server** + ```bash + bash tools/run-docker-server.sh + ``` + +4. **Start the frontend application** + ```bash + bash tools/run-docker-client.sh + ``` + +5. **Access the application** + - Frontend: http://localhost:5000 + - API Documentation: http://localhost:8080/swagger-ui.html + +## ๐Ÿ› ๏ธ Development + +### Frontend Development +```bash +cd client +npm install # Install dependencies +npm start # Start development server (port 5000) +npm run build # Build for production +npm run preview # Preview production build +npm run lint # Run ESLint +npm run lint:fix # Fix ESLint issues +``` + +### Backend Development +```bash +cd server +./mvnw spring-boot:run # Start development server +./mvnw clean compile # Compile sources +./mvnw spring-boot:build-image # Build Docker image +./mvnw clean verify -Pnative # Build GraalVM native image +``` + +### Quality Checks +Run quality checks before submitting changes: +```bash +bash tools/check-frontend.sh # Frontend linting, testing, coverage +bash tools/check-backend.sh # Backend compilation, tests, checkstyle +``` + +## ๐Ÿงช Testing + +### Frontend Testing +- **Framework**: Vitest with React Testing Library +- **Coverage**: Comprehensive test coverage with reports in `client/coverage/` +- **Commands**: + ```bash + npm test # Run tests in watch mode + npm run test:coverage # Generate coverage report + ``` + +### Backend Testing +- **Unit Tests**: Fast, isolated tests with mocked dependencies +- **Integration Tests**: Full application context with test database +- **Coverage**: JaCoCo reporting with 75% minimum requirement +- **Commands**: + ```bash + ./mvnw test # Unit tests only + ./mvnw clean verify -Ptests # All tests with coverage + ``` + +## ๐Ÿ“ฆ Deployment + +### Production Deployment +The application supports multiple deployment strategies: + +1. **Docker Containers** (recommended) + ```bash + docker-compose -f docker-compose.prod.yml up -d + ``` + +2. **Traditional JAR Deployment** + ```bash + cd server && ./mvnw clean package + java -jar target/tasknote-api.jar + ``` + +3. **GraalVM Native Image** (for optimal performance) + ```bash + cd server && ./mvnw clean verify -Pnative + ./target/tasknote-api + ``` + +### Environment Configuration +- Database connection via environment variables +- JWT secret configuration for production +- Email service configuration for notifications +- CORS settings for frontend domain + +## ๐Ÿค Contributing + +We welcome contributions from the community! This project follows the **Fork & Merge** workflow. + +### How to Contribute + +1. **Fork the Project** on GitHub +2. **Clone your fork** locally + ```bash + git clone https://github.com/YOUR_USERNAME/react-typescript-todolist.git + ``` +3. **Create a feature branch** + ```bash + git checkout -b feature/amazing-feature + ``` +4. **Make your changes** and ensure they follow the project standards +5. **Run quality checks** + ```bash + bash tools/check-frontend.sh + bash tools/check-backend.sh + ``` +6. **Commit your changes** + ```bash + git commit -m 'Add some amazing feature' + ``` +7. **Push to your fork** + ```bash + git push origin feature/amazing-feature + ``` +8. **Open a Pull Request** with a detailed description + +### Development Guidelines +- Follow existing code conventions and patterns +- Write tests for new functionality +- Update documentation when necessary +- Ensure all quality checks pass +- Keep commits focused and descriptive + +For detailed setup instructions and development workflows, see [CONTRIBUTING.md](CONTRIBUTING.md). + +## ๐Ÿ‘จโ€๐Ÿ’ป Developer + +**Ricardo Campos** - Full-Stack Developer & Project Maintainer + +- **GitHub**: [@ricardo-campos-org](https://github.com/ricardo-campos-org) +- **Twitter/X**: [@RMCamposs](https://x.com/RMCamposs) +- **LinkedIn**: [Ricardo Campos](https://www.linkedin.com/in/ricardo-campos-org/) + +### About the Developer +Ricardo is a passionate full-stack developer with expertise in modern web technologies, cloud architecture, and agile development practices. This project showcases his skills in: + +- **Frontend Development**: React, TypeScript, modern CSS, responsive design +- **Backend Development**: Java, Spring Boot, RESTful APIs, microservices +- **DevOps & Infrastructure**: Docker, CI/CD, cloud deployment, monitoring +- **Software Quality**: Testing strategies, code coverage, static analysis +- **Open Source**: Community engagement, documentation, maintainership + +The TaskNote project represents a commitment to clean code, comprehensive testing, and user-centered design principles. ## ๐Ÿ“ž Contact -Reach out on X [@RMCamposs](https://x.com/RMCamposs) +For questions, suggestions, or collaboration opportunities: + +- **Email**: Contact via GitHub issues or discussions +- **Twitter/X**: [@RMCamposs](https://x.com/RMCamposs) for quick questions +- **GitHub Issues**: [Create an issue](https://github.com/ricardo-campos-org/react-typescript-todolist/issues) for bugs or feature requests +- **GitHub Discussions**: [Join discussions](https://github.com/ricardo-campos-org/react-typescript-todolist/discussions) for general questions ## ๐Ÿ“„ License -Distributed under GPLv3 License. See `LICENSE` for more information. +This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details. + +### What this means: +- โœ… **Freedom to use**: Use the software for any purpose +- โœ… **Freedom to study**: Access and modify the source code +- โœ… **Freedom to share**: Distribute copies of the software +- โœ… **Freedom to improve**: Distribute modified versions + +**Copyleft**: Any derivative work must also be open source under GPL v3.0 + +--- + +โญ **Star this repository if you find it helpful!** โญ diff --git a/server/pom.xml b/server/pom.xml index f9a85d0..b32bd2d 100644 --- a/server/pom.xml +++ b/server/pom.xml @@ -5,7 +5,7 @@ org.springframework.boot spring-boot-starter-parent - 3.5.4 + 3.5.5 @@ -176,17 +176,17 @@ io.jsonwebtoken jjwt-api - 0.12.7 + 0.12.6 io.jsonwebtoken jjwt-impl - 0.12.7 + 0.12.6 io.jsonwebtoken jjwt-jackson - 0.12.7 + 0.12.6 diff --git a/server/src/main/resources/META-INF/native-image/reflect-config.json b/server/src/main/resources/META-INF/native-image/reflect-config.json index 1dd43af..5f37561 100644 --- a/server/src/main/resources/META-INF/native-image/reflect-config.json +++ b/server/src/main/resources/META-INF/native-image/reflect-config.json @@ -119,6 +119,57 @@ } ] }, + { + "condition": { + "typeReachable": "io.jsonwebtoken.impl.DefaultJwtParserBuilder" + }, + "name": "io.jsonwebtoken.impl.DefaultJwtParserBuilder$Supplier", + "allDeclaredConstructors": true, + "allPublicConstructors": true, + "allDeclaredMethods": true, + "allPublicMethods": true, + "allDeclaredFields": true, + "allPublicFields": true + }, + { + "condition": { + "typeReachable": "io.jsonwebtoken.impl.DefaultJwtParserBuilder" + }, + "name": "io.jsonwebtoken.impl.DefaultJwtParser", + "allDeclaredConstructors": true, + "allPublicConstructors": true, + "allDeclaredMethods": true, + "allPublicMethods": true, + "allDeclaredFields": true, + "allPublicFields": true + }, + { + "name": "io.jsonwebtoken.impl.DefaultJwtParserBuilder$Supplier", + "allDeclaredConstructors": true, + "allPublicConstructors": true, + "allDeclaredMethods": true, + "allPublicMethods": true, + "allDeclaredFields": true, + "allPublicFields": true + }, + { + "name": "io.jsonwebtoken.impl.DefaultJwtParser", + "allDeclaredConstructors": true, + "allPublicConstructors": true, + "allDeclaredMethods": true, + "allPublicMethods": true, + "allDeclaredFields": true, + "allPublicFields": true + }, + { + "name": "io.jsonwebtoken.impl.DefaultJwtParserBuilder", + "allDeclaredConstructors": true, + "allPublicConstructors": true, + "allDeclaredMethods": true, + "allPublicMethods": true, + "allDeclaredFields": true, + "allPublicFields": true + }, { "condition": { "typeReachable": "io.jsonwebtoken.CompressionCodecs" @@ -575,4 +626,4 @@ } ] } -] +] \ No newline at end of file