docs: add README.md

Author: omeralpi

README.md

@@ -0,0 +1,128 @@
+# 🐾 Felisnovel API
+
+> **A robust, scalable API built with [AdonisJS](https://adonisjs.com/) and TypeScript, designed for modern web applications.**
+
+---
+
+## ✨ Features
+
+- **AdonisJS 5**: Modern Node.js MVC framework with TypeScript support.
+- **Comprehensive CRUD Factory**: Instantly generate models, controllers, migrations, factories, validators, and functional tests for any entity.
+- **Extensive Functional Testing**: Uses [@japa/runner](https://github.com/japa-js/japa) for end-to-end and API tests.
+- **Modular Structure**: Clean separation of concerns for scalability and maintainability.
+
+---
+
+## 🚀 Getting Started
+
+1. **Install dependencies**
+   ```bash
+   yarn install
+   ```
+
+2. **Configure environment**
+   - Copy `.env.example` to `.env` and fill in the required variables.
+   - See `env.ts` for all required environment variables.
+
+3. **Run migrations & seeders**
+   ```bash
+   yarn mf      # Fresh migration
+   yarn mfs     # Fresh migration with seeders
+   ```
+
+4. **Start the development server**
+   ```bash
+   yarn dev
+   ```
+
+---
+
+## 🏭 CRUD Factory
+
+Easily scaffold a full CRUD flow for any entity using the custom Ace command:
+
+```bash
+node ace crud <EntityName>
+```
+
+- Generates:
+  - Model (`app/Models/`)
+  - Controller (`app/Controllers/Http/`)
+  - Migration (`database/migrations/`)
+  - Factory (`database/factories/`)
+  - Validator (`app/Validators/`)
+  - Functional Test (`tests/functional/`)
+
+**Example:**
+```bash
+node ace crud Country
+node ace crud Country --interactive
+```
+
+---
+
+## 🧪 Testing
+
+All tests are written with [@japa/runner](https://github.com/japa-js/japa) and live in `tests/functional/`.
+
+### How to run tests
+
+```bash
+yarn test
+# or
+node ace test
+```
+
+### Test Philosophy
+
+- **Functional Coverage:** Every CRUD endpoint, authentication flow, and business rule is covered by functional tests.
+- **Factories:** Test data is generated using AdonisJS factories for realistic and isolated scenarios.
+- **Role-based Testing:** Many tests check both admin and regular user permissions, ensuring robust access control.
+- **Setup & Teardown:** Each test group uses a `cleanAll` setup to ensure a clean database state.
+- **Assertions:** Tests assert HTTP status codes, response bodies, and side effects (like DB changes or emails sent).
+
+### Test Structure
+
+- **Grouped by Resource:** Each `.spec.ts` file targets a specific resource (e.g., `users`, `novels`, `contacts`).
+- **Example Test:**
+  ```ts
+  test('create a country', async ({ client }) => {
+    const admin = await UserFactory.apply('admin').create()
+    const data = { name: 'Turkey', key: 'TR' }
+    const response = await client.post('/countries').loginAs(admin).form(data)
+    response.assertStatus(200)
+    response.assertBodyContains(data)
+  })
+  ```
+- **Plugins & Reporters:**  
+  - Uses `@japa/preset-adonis` for assertions, API client, and failed test reruns.
+  - Spec reporter for detailed terminal output.
+- **Automated Setup:**  
+  - Migrations and seeders run automatically before tests.
+  - HTTP server starts for functional suites.
+
+### Advanced
+
+- **Test utilities**: Common helpers (like `cleanAll`) are in `tests/utils/`.
+- **Email and notification flows** are tested using AdonisJS mail fakes and notification assertions.
+- **Reports and analytics endpoints** are covered with realistic data and assertions.
+
+---
+
+## 🛠️ Example Ace Commands
+
+- `node ace crud <EntityName>` – Scaffold full CRUD for an entity
+- `node ace test` – Run all tests
+- `node ace migration:run` – Run migrations
+- `node ace db:seed` – Seed the database
+
+See all available commands:
+```bash
+node ace list
+```
+
+---
+
+## 📄 License
+
+MIT