arky-js/README.md

**Arky.js** is a powerful, annotation-based framework for building serverless applications on **AWS Lambda and API Gateway**. Inspired by Angular and NestJS, Arky.js simplifies serverless development by providing decorators for defining modules, controlle

# Arky.js

**Arky.js** is a powerful, annotation-based framework for building serverless applications on **AWS Lambda and API Gateway**. Inspired by Angular and NestJS, Arky.js simplifies serverless development by providing decorators for defining modules, controllers, and services. It compiles your structured code into a fully functional Serverless application.

Currently, Arky.js supports **AWS** only, but future versions aim to support multiple cloud providers (like **GCP** and **Azure**) — **without changing your business logic or project structure**.

---


## ✨ Features

- **Annotation-based architecture** (`@Module`, `@Controller`, `@Get`, `@Post`, etc.)
- **Dependency Injection** for modular and scalable services
- **Automatic compilation to cloud functions with deployment scripts**
- **Controller-to-Lambda mapping** – each controller is deployed as a separate cloud function
- **Built-in CLI** for building and deploying projects (`arky build`, `arky deploy`)

---


## 📆 Installation

Install Arky.js either globally or as a local dependency:

```bash
# Global install
npm install -g arky-js

# OR: Local project install
npm install --save arky-js
```

---


## Peer Dependencies

Install these in your project:

```bash
npm install express@^4.18.2 aws-serverless-express@^3.4.0 aws-cdk-lib@2.186.0
```

---


## 🗂 Project Structure

Arky.js encourages a clean, modular structure:

```

project-root/
├── src/
│ ├── app.module.ts
│ ├── user/
│ │ ├── user.module.ts
│ │ ├── user.controller.ts
│ │ └── user.service.ts
│ └── main.ts
├── arky.config.json # Project configuration
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

```

---


## 🧹 Example Code

### 1. Define a Module

```ts
import { Module } from "arky-js";
import { UserController } from "./user.controller";
import { UserService } from "./user.service";

@Module({
  controllers: [UserController],
  providers: [UserService],
})
export class UserModule {}
```

### 2. Create a Controller

```ts
import { Controller, Get, Post } from "arky-js";
import { UserService } from "./user.service";

@Controller("/users")
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get("/")
  getAllUsers() {
    return this.userService.getUsers();
  }

  @Post("/")
  createUser() {
    return this.userService.createUser();
  }
}
```

### 3. Implement a Service

```ts
import { Injectable } from "arky-js";

@Injectable()
export class UserService {
  private users = [{ id: 1, name: "John Doe" }];

  getUsers() {
    return this.users;
  }

  createUser() {
    const newUser = { id: Date.now(), name: "New User" };
    this.users.push(newUser);
    return newUser;
  }
}
```

---


## 🛠 CLI Commands

Arky.js provides a powerful CLI for compiling and deploying your project.

### Build the project

```bash
arky build
```

Compiles your annotated source code into cloud-specific, deployable files.

### Deploy to the cloud

```bash
arky deploy
```

Deploys your compiled serverless project to AWS (more cloud support coming soon).

---


## 📄 `arky.config.json` Configuration File

The `arky.config.json` file is used to store the configuration settings for your Arky.js project. It helps Arky.js understand the structure of your application and which cloud platform you are targeting for deployment. While Arky.js currently supports **AWS** only, the configuration file is designed to support future platforms like **GCP** and **Azure**.

### Configuration Parameters

- **`rootModule`**:  
  Define application root module and default it consider as `app.module.ts`

- **`platform`**:  
  Specifies the cloud platform to target during the build process. Currently, the only accepted values (`aws`).

  Example:

  ```json
  {
    "rootModule": "app.module.ts",
    "platform": "aws"
  }
  ```

## 📄 License

This project is licensed under the **ISC License** – see the [LICENSE](LICENSE) file for details.

---


## 🚀 Roadmap & Future Improvements

- 🔌 **Database integration**
- ⚡ `@Function()` decorator to handle other AWS events (e.g., S3, DynamoDB, EventBridge)
- ☁️ Multi-cloud support (e.g., GCP, Azure)
- 🏗 Advanced IaC (Infrastructure as Code) generation for different cloud platforms
- 💡 Improved developer tools and CLI scaffolding

---


**Contributions are welcome!** Whether you're fixing bugs, adding features, or suggesting ideas — join us in shaping the future of serverless development! 🙌