Rewrite README: restructure documentation with architecture, setup, and local development instructions

README.md

@@ -1,261 +1,174 @@
-<div id="top">
+# Taskfy
 
-<!-- HEADER STYLE: CLASSIC -->
-<div align="center">
-
-
-# TASKFY
-
-<em>Transforming Tasks Into Seamless Success</em>
-
-<!-- BADGES -->
-<img src="https://img.shields.io/github/last-commit/syntaxmage05/taskfy?style=flat&logo=git&logoColor=white&color=0080ff" alt="last-commit">
-<img src="https://img.shields.io/github/languages/top/syntaxmage05/taskfy?style=flat&color=0080ff" alt="repo-top-language">
-<img src="https://img.shields.io/github/languages/count/syntaxmage05/taskfy?style=flat&color=0080ff" alt="repo-language-count">
-
-<em>Built with the tools and technologies:</em>
-
-<img src="https://img.shields.io/badge/JSON-000000.svg?style=flat&logo=JSON&logoColor=white" alt="JSON">
-<img src="https://img.shields.io/badge/Markdown-000000.svg?style=flat&logo=Markdown&logoColor=white" alt="Markdown">
-<img src="https://img.shields.io/badge/npm-CB3837.svg?style=flat&logo=npm&logoColor=white" alt="npm">
-<img src="https://img.shields.io/badge/Ruby-CC342D.svg?style=flat&logo=Ruby&logoColor=white" alt="Ruby">
-<img src="https://img.shields.io/badge/PostCSS-DD3A0A.svg?style=flat&logo=PostCSS&logoColor=white" alt="PostCSS">
-<img src="https://img.shields.io/badge/Prettier-F7B93E.svg?style=flat&logo=Prettier&logoColor=black" alt="Prettier">
-<img src="https://img.shields.io/badge/esbuild-FFCF00.svg?style=flat&logo=esbuild&logoColor=black" alt="esbuild">
-<img src="https://img.shields.io/badge/JavaScript-F7DF1E.svg?style=flat&logo=JavaScript&logoColor=black" alt="JavaScript">
-<img src="https://img.shields.io/badge/i18next-26A69A.svg?style=flat&logo=i18next&logoColor=white" alt="i18next">
-<br>
-<img src="https://img.shields.io/badge/React-61DAFB.svg?style=flat&logo=React&logoColor=black" alt="React">
-<img src="https://img.shields.io/badge/Yarn-2C8EBB.svg?style=flat&logo=Yarn&logoColor=white" alt="Yarn">
-<img src="https://img.shields.io/badge/Docker-2496ED.svg?style=flat&logo=Docker&logoColor=white" alt="Docker">
-<img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat&logo=GitHub-Actions&logoColor=white" alt="GitHub%20Actions">
-<img src="https://img.shields.io/badge/Vite-646CFF.svg?style=flat&logo=Vite&logoColor=white" alt="Vite">
-<img src="https://img.shields.io/badge/ESLint-4B32C3.svg?style=flat&logo=ESLint&logoColor=white" alt="ESLint">
-<img src="https://img.shields.io/badge/Axios-5A29E4.svg?style=flat&logo=Axios&logoColor=white" alt="Axios">
-<img src="https://img.shields.io/badge/Sass-CC6699.svg?style=flat&logo=Sass&logoColor=white" alt="Sass">
-<img src="https://img.shields.io/badge/Buffer-231F20.svg?style=flat&logo=Buffer&logoColor=white" alt="Buffer">
-
-</div>
-<br>
-
----
-
-## Table of Contents
+Taskfy is a full-stack task management application built with **Ruby on Rails 8** and **React**. It provides a JSON API for core resources (tasks, users, sessions, comments) and serves a SPA-style frontend shell from Rails.
 
+## Contents
 - [Overview](#overview)
-- [Getting Started](#getting-started)
-    - [Prerequisites](#prerequisites)
-    - [Installation](#installation)
-    - [Usage](#usage)
-    - [Testing](#testing)
-- [Features](#features)
-- [Project Structure](#project-structure)
-
----
+- [Architecture](#architecture)
+- [Tech Stack](#tech-stack)
+- [API](#api)
+- [Repository Layout](#repository-layout)
+- [Local Development](#local-development)
+- [Testing & Code Quality](#testing--code-quality)
+- [Deployment](#deployment)
+- [Troubleshooting](#troubleshooting)
 
 ## Overview
 
-Taskfy is a powerful developer toolkit designed to streamline the development, deployment, and maintenance of modern Rails applications integrated with React. It combines robust dependency management, frontend asset optimization, and containerized workflows to enhance productivity and scalability.
-
-**Why Taskfy?**
-
-This project simplifies complex workflows by providing:
-
-- 🧩 **Dependency & Environment Management:** Ensures a consistent, scalable Rails setup with Gemfile, credentials, and environment configs.
-- 🚀 **Frontend Asset Optimization:** Uses esbuild, Tailwind CSS, and Vite for fast, modern frontend builds.
-- 🐳 **Containerized Deployment:** Dockerfile and Procfile.dev facilitate reliable, repeatable environments.
-- 🎯 **Testing & Quality Assurance:** Factory setups, parallel test execution, and system tests improve code reliability.
-- 🔒 **Secure & Maintainable:** Encrypted credentials, security policies, and clear separation of concerns support long-term stability.
-
----
-
-## Features
-
-|      | Component            | Details                                                                                     |
-| :--- | :------------------- | :------------------------------------------------------------------------------------------ |
-| ⚙️  | **Architecture**     | <ul><li>Ruby on Rails backend with React on the frontend</li><li>Ruby API and React on the frontend structure</li></ul> |
-| 🔩 | **Code Quality**     | <ul><li>Uses RuboCop for linting</li><li>Consistent code style with Prettier & ESLint for frontend</li><li>Includes Rake tasks for automation</li></ul> |
-| 📄 | **Documentation**    | <ul><li>Dockerfile for containerization</li><li>README.md with project overview</li><li>Config files (.yml, .json) for setup</li></ul> |
-| 🔌 | **Integrations**      | <ul><li>GitHub Actions for CI/CD pipeline</li><li>Docker for containerization</li><li>Bundler, npm, yarn for dependency management</li></ul> |
-| 🧩 | **Modularity**        | <ul><li>Frontend components built with React, modularized via Vite</li><li>CSS handled with TailwindCSS, utility-first approach</li><li>Backend separated into controllers, models, services</li></ul> |
-| 🧪 | **Testing**           | <ul><li>RSpec for backend tests</li><li>Jest and React Testing Library for frontend</li><li>CI pipeline runs tests on push</li></ul> |
-| ⚡️  | **Performance**       | <ul><li>Vite used for fast frontend builds</li><li>Asset optimization with esbuild and TailwindCSS</li><li>Caching strategies via Rails cache.yml</li></ul> |
-| 🛡️ | **Security**          | <ul><li>Encrypted credentials via credentials.yml.enc</li><li>Secure environment variables in CI/CD</li><li>Dependabot for dependency updates</li></ul> |
-| 📦 | **Dependencies**      | <ul><li>Backend: Ruby gems managed via Gemfile & Gemfile.lock</li><li>Frontend: npm/yarn with package.json & yarn.lock</li><li>CI/CD: docker, github_actions, rake</li></ul> |
-
----
-
-## Project Structure
-
-```sh
-└── taskfy/
-    ├── .github
-    │   ├── dependabot.yml
-    │   └── workflows
-    ├── Dockerfile
-    ├── Gemfile
-    ├── Gemfile.lock
-    ├── Procfile.dev
-    ├── README.md
-    ├── Rakefile
-    ├── app
-    │   ├── assets
-    │   ├── controllers
-    │   ├── helpers
-    │   ├── javascript
-    │   ├── jobs
-    │   ├── mailers
-    │   ├── models
-    │   ├── policies
-    │   └── views
-    ├── config
-    │   ├── application.rb
-    │   ├── boot.rb
-    │   ├── build
-    │   ├── cable.yml
-    │   ├── cache.yml
-    │   ├── credentials.yml.enc
-    │   ├── database.yml.ci
-    │   ├── deploy.yml
-    │   ├── environment.rb
-    │   ├── environments
-    │   ├── initializers
-    │   ├── locales
-    │   ├── puma.rb
-    │   ├── queue.yml
-    │   ├── recurring.yml
-    │   ├── routes.rb
-    │   └── storage.yml
-    ├── config.ru
-    ├── db
-    │   ├── cable_schema.rb
-    │   ├── cache_schema.rb
-    │   ├── data
-    │   ├── data_schema.rb
-    │   ├── migrate
-    │   ├── queue_schema.rb
-    │   ├── schema.rb
-    │   └── seeds.rb
-    ├── esbuild.config.js
-    ├── lib
-    │   └── tasks
-    ├── package.json
-    ├── postcss.config.js
-    ├── script
-    │   └── .keep
-    ├── tailwind.config.js
-    ├── test
-    │   ├── application_system_test_case.rb
-    │   ├── controllers
-    │   ├── factories
-    │   ├── helpers
-    │   ├── integration
-    │   ├── mailers
-    │   ├── models
-    │   ├── support
-    │   ├── system
-    │   └── test_helper.rb
-    ├── vite.config.js
-    ├── vite.config.mts
-    └── yarn.lock
+Taskfy is designed for a Rails-first backend workflow with a modern frontend toolchain.
+
+- Rails handles domain logic, persistence, and JSON responses.
+- React handles interactive UI components in the frontend shell.
+- Vite/esbuild provide fast frontend development and bundling.
+- SQLite keeps local setup lightweight.
+
+## Architecture
+
+- **Backend framework:** Rails 8 (`config.load_defaults 8.0`)
+- **API rendering:** Jbuilder templates under `app/views/**/.json.jbuilder`
+- **Auth/session flow:** session resource (`POST /session`, `DELETE /session`)
+- **Authorization:** Pundit policy layer (e.g., `app/policies/task_policy.rb`)
+- **Frontend entrypoint:** `app/javascript/src/App.jsx` served through Rails routing fallback
+
+## Tech Stack
+
+### Backend
+- Ruby on Rails `~> 8.0.4`
+- SQLite3
+- Pundit
+- Jbuilder
+- Solid Queue / Solid Cache / Solid Cable
+
+### Frontend
+- React 18
+- Vite
+- esbuild
+- Sass
+- Tailwind CSS
+
+### Tooling
+- RuboCop
+- ESLint + Prettier
+- Brakeman
+- Husky + lint-staged
+
+## API
+
+JSON routes are defined with a `format: :json` constraint in `config/routes.rb`.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/tasks` | List tasks |
+| POST | `/tasks` | Create task |
+| GET | `/tasks/:slug` | Get task by slug |
+| PATCH / PUT | `/tasks/:slug` | Update task |
+| DELETE | `/tasks/:slug` | Delete task |
+| GET | `/users` | List users |
+| POST | `/users` | Create user |
+| POST | `/session` | Sign in / create session |
+| DELETE | `/session` | Sign out / destroy session |
+| POST | `/comments` | Create comment |
+
+## Repository Layout
+
+```text
+taskfy/
+├── app/
+│   ├── controllers/       # Request handling and API actions
+│   ├── javascript/        # React source, entrypoints, stylesheets
+│   ├── models/            # ActiveRecord models
+│   ├── policies/          # Pundit authorization policies
+│   └── views/             # ERB and Jbuilder templates
+├── config/                # Rails config, routes, env settings
+├── db/                    # Schema and migration/data files
+├── bin/                   # Dev and maintenance scripts
+├── Procfile.dev           # Foreman process definitions
+├── Gemfile                # Ruby gems
+└── package.json           # JavaScript dependencies/scripts
 ```
 
----
-
-## Getting Started
+## Local Development
 
 ### Prerequisites
 
-This project requires the following dependencies:
+Install:
+- Ruby (version compatible with `.ruby-version`)
+- Bundler
+- Node.js + Yarn
+- SQLite3
 
-- **Programming Language:** Ruby
-- **Package Manager:** Bundler, Rake, Npm, Yarn
-- **Container Runtime:** Docker
+### Setup
 
-### Installation
+```bash
+git clone <repo-url>
+cd taskfy
+bundle install
+yarn install
+bin/rails db:prepare
+```
 
-Build taskfy from the source and install dependencies:
+Alternative bootstrap flow:
 
-1. **Clone the repository:**
+```bash
+bin/setup
+```
 
-    ```sh
-    ❯ git clone https://github.com/syntaxmage05/taskfy
-    ```
+### Run
 
-2. **Navigate to the project directory:**
+```bash
+bin/dev
+```
 
-    ```sh
-    ❯ cd taskfy
-    ```
+`bin/dev` uses `Procfile.dev` and starts:
+- Rails server
+- JS build watcher
+- Vite dev server
 
-3. **Install the dependencies:**
+Default URL: `http://localhost:3000`
 
-**Using [docker](https://www.docker.com/):**
+## Testing & Code Quality
 
-```sh
-❯ docker build -t syntaxmage05/taskfy .
-```
-**Using [bundler](https://www.ruby-lang.org/):**
+### Tests
 
-```sh
-❯ bundle install
+```bash
+bin/rails test
 ```
-**Using [npm](https://www.npmjs.com/):**
 
-```sh
-❯ npm install
-```
-**Using [yarn](https://yarnpkg.com/):**
+### Ruby linting
 
-```sh
-❯ yarn install
+```bash
+bin/rubocop
 ```
 
-### Usage
-
-Run the project with:
-
-**Using [docker](https://www.docker.com/):**
+### Security scan
 
-```sh
-docker run -it {image_name}
+```bash
+bin/brakeman
 ```
-**Using [bundler](https://www.ruby-lang.org/):**
 
-```sh
-bundle exec ruby {entrypoint}
-```
-**Using [npm](https://www.npmjs.com/):**
-
-```sh
-npm start
-```
-**Using [yarn](https://yarnpkg.com/):**
+### JavaScript lint/format (examples)
 
-```sh
-yarn start
+```bash
+yarn eslint app/javascript --ext .js,.jsx
+yarn prettier --check "app/javascript/**/*.{js,jsx}"
 ```
 
-### Testing
+## Deployment
 
-Taskfy uses the {ruby__test_framework} test framework. Run the test suite with:
+The repository includes Docker and Kamal configuration.
 
-```sh
-rails test
-```
-**Using [npm](https://www.npmjs.com/):**
-
-```sh
-npm test
-```
-**Using [yarn](https://yarnpkg.com/):**
+Build a local image:
 
-```sh
-yarn test
+```bash
+docker build -t taskfy:latest .
 ```
 
----
+Before deploying, review:
+- `config/deploy.yml`
+- `.kamal/secrets`
 
-<div align="left"><a href="#top">⬆ Return</a></div>
+## Troubleshooting
 
----
+- **Port conflict:** `PORT=3001 bin/dev`
+- **Dependency mismatch:** rerun `bundle install` and `yarn install`
+- **Database reset:** `bin/rails db:drop db:create db:migrate`