From 318896d425b7fc002f38774cac2cff349f45fc53 Mon Sep 17 00:00:00 2001 From: Sosokker Date: Mon, 21 Apr 2025 00:48:13 +0700 Subject: [PATCH] chore: update README and Makefile --- README.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++ backend/Makefile | 6 +-- 2 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f8461f6 --- /dev/null +++ b/README.md @@ -0,0 +1,137 @@ +# Project Report: Full-Stack Todo List Application + +## 1. Overview + +This report covers the design, tech stack, and setup process for our Todo List app. The app lets users manage tasks, add tags, create subtasks, and attach images. Users can sign in with email/password or Google. We built the backend with Go using Hexagonal Architecture and the frontend with Next.js, React, and TypeScript. + +## 2. Tech Stack + +### Backend: + +* **Language:** Go +* **Web Framework:** Chi (v5) - Handles HTTP routing and middleware +* **Database Tools:** + * `pgx/v5`: PostgreSQL driver + * `sqlc`: Turns SQL queries into Go code + * `golang-migrate`: Manages database schema changes +* **API Tools:** + * OpenAPI 3.0: Defines the API + * `oapi-codegen`: Creates Go code from OpenAPI specs +* **Auth Tools:** + * JWT: For token generation and checking + * bcrypt: For password hashing + * OAuth2: For Google login +* **Other Tools:** + * `viper`: Manages app settings + * `slog`: For logging + * `go-cache`: For temporary data storage + * Google Cloud Storage: For file storage + +### Frontend: + +* **Framework:** Next.js (v15+) with App Router +* **Language:** TypeScript +* **UI:** React (v19+) +* **Styling:** Tailwind CSS (v4+) +* **Component Library:** shadcn/ui (built on Radix UI) +* **State Management:** + * Zustand: For app-wide state (like login status) + * TanStack Query: For server data, caching, and syncing +* **Forms:** React Hook Form +* **Drag & Drop:** @dnd-kit (for Kanban board) +* **Other Tools:** sonner (for notifications), date-fns, lucide-react (icons) + +## 3. Database + +* **Type:** PostgreSQL +* **Tables:** + * `users`: Stores user info and login details + * `tags`: User-created labels with name, color, and icon + * `todos`: Main task items with title, description, status, deadline, and attachment link + * `subtasks`: Step-by-step items for each todo + * `todo_tags`: Links todos to tags (many-to-many) +* **Features:** + * Indexes on frequently searched columns for speed + * Auto-updated timestamp columns + +## 4. Setup Guide + +### Requirements: + +* Go (version 1.24+) +* Node.js (v20+ recommended) +* pnpm (or npm/yarn) +* PostgreSQL Database +* Command line tools: `migrate`, `sqlc`, `oapi-codegen` +* Google Cloud Storage account and bucket + +### Backend Setup: + +1. **Get the code:** `git clone https://github.com/Sosokker/go-chi-oapi-codegen-todolist.git` +2. **Go to backend folder:** `cd backend` +3. **Set up config:** + * Copy `example.config.yaml` to `config.yaml` + * Update database connection, JWT secret, Google OAuth settings, and GCS bucket name + * Add your GCS credentials file +4. **Set up database:** + * Use your own PostgreSQL server and provide postgres connection string +5. **Update `DB_URL` and `MIGRATIONS_PATH`** in `Makefile` + * `DB_URL`: Your PostgreSQL connection string + * `MIGRATIONS_PATH`: Path to your migrations directory (Absolute Path) +6. **Run database setup:** `make migrate-up` +7. **Start the backend:** + * Regular mode: `make run` + * Development mode: `make dev` (auto-reloads on changes) + +### Frontend Setup: + +1. **Go to frontend folder:** `cd ../frontend` +2. **Install packages:** `pnpm install` +3. **Create config file:** + * Make a `.env.local` file with: + ``` + NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/api/v1 + ``` +4. **Start the frontend:** `pnpm dev` + +The app should now run at `http://localhost:3000`. + +## 5. Code Architecture + +### Overall Design: + +* **Backend:** Provides a REST API, handles business logic, data storage, and auth +* **Frontend:** Creates user interface and manages user interactions +* **Communication:** Frontend sends HTTP requests to backend API endpoints + +### Backend Architecture (Hexagonal): + +The backend follows a "ports and adapters" pattern for better separation of concerns: + +1. **Core Domain:** Basic business objects (`User`, `Todo`, `Tag`) and logic +2. **Service Layer:** Contains the main business rules and coordinates operations +3. **Ports (Interfaces):** Define contracts for different parts of the system +4. **Adapters:** Implement the interfaces, connecting the app to external systems: + * API handlers (connect HTTP to services) + * Database repositories (connect services to database) + * Storage service (connects to Google Cloud) + +### Frontend Architecture: + +1. **Pages & Routes:** In the `app/` folder using Next.js App Router +2. **Components:** + * `components/ui/`: Basic UI elements (buttons, inputs, etc.) + * `components/`: App-specific components (TodoCard, TodoForm, etc.) +3. **State Management:** + * Server data: TanStack Query fetches and caches API data + * Client state: Zustand manages user login status +4. **API Calls:** Centralized in service files for consistency + +### Key Design Choices: + +* **Hexagonal Architecture:** Separates business logic from external systems +* **OpenAPI First:** Clearly defines API before coding +* **sqlc:** Generates type-safe database code +* **Cloud Storage:** Stores file attachments separately from database +* **Caching:** Improves performance for frequently accessed data +* **Modern Frontend:** Uses latest React patterns and tools \ No newline at end of file diff --git a/backend/Makefile b/backend/Makefile index 76b9b14..326f4ac 100644 --- a/backend/Makefile +++ b/backend/Makefile @@ -73,16 +73,12 @@ test: migrate-up: @echo ">> Applying migrations..." - $(MIGRATE) -database "$(DB_URL)" -path $(MIGRATIONS_PATH) up + $(MIGRATE) -database "$(DB_URL)" -path $(MIGRATIONS_PATH) up 2 migrate-down: @echo ">> Rolling back last migration..." $(MIGRATE) -database "$(DB_URL)" -path $(MIGRATIONS_PATH) down 1 -migrate-force: - @echo ">> Forcing migration version $(VERSION)..." - $(MIGRATE) -database "$(DB_URL)" -path $(MIGRATIONS_PATH) force $(VERSION) - clean: @echo ">> Cleaning build artifacts..." rm -rf $(OUTPUT_DIR) \ No newline at end of file