Cloudrave Cloud Storage Development

GitHub Copilot instructions for working in the Cloudrave repository — a mini cloud storage app similar to Google Drive, Mediafire, or Dropbox.

What This Does

Provides targeted, actionable context for GitHub Copilot when working in the Cloudrave codebase. Includes architecture overview, critical flows, environment variables, dev commands, and project-specific conventions.

Architecture Overview

**Backend:** `cloud-storage-backend`

**Frontend:** `cloud-storage-frontend`

**Storage:** AWS S3

Critical Flows

Authentication

**JWT-based auth with custom header convention:**

```javascript

// Backend middleware: cloud-storage-backend/middleware/auth.js

// Expects token in 'x-auth-token' header (NOT 'Authorization: Bearer')

const token = req.header('x-auth-token');

```

**Registration/login:**

Three-Step Upload Flow

1. **Generate presigned URL:**

```javascript

POST /api/files/generate-upload-url

// Returns: { uploadUrl, s3Key }

```

2. **Client uploads directly to S3:**

```javascript

PUT uploadUrl

// Body: file bytes

```

3. **Finalize metadata:**

```javascript

POST /api/files/finalize-upload

// Body: { originalFilename, s3Key, mimetype, fileSize }

```

**S3 key format:** `uploads/${userId}/${Date.now()}-${filename}`

**Implementation:** `cloud-storage-backend/routes/files.js`

Environment & Secrets

Backend Environment Variables

Required in `cloud-storage-backend`:

Frontend Secrets Warning

⚠️ **Security Note:**

Dev Commands

Frontend (`cloud-storage-frontend/package.json`)

```bash

npm run dev # Start Vite dev server

npm run build # Build for production

npm run preview # Preview production build

```

Backend (`cloud-storage-backend/package.json`)

```bash

node index.js # Start API server

nodemon index.js # Development mode with auto-reload

```

**Note:** No dev script defined. Main entry: `index.js`. Ensure environment variables are set before starting.

Project Conventions

TypeScript Types (`types.ts`)

Core types for frontend:

**Keep UI state consistent with these types.**

File Metadata Fields

Use these exact field names:

Auth Header Convention

**Always use `x-auth-token` header for protected endpoints** (not `Authorization: Bearer`).

```javascript

// Example request

fetch('/api/files', {

headers: {

'x-auth-token': token

}

});

```

Key Files to Check First

Backend Routes

Backend Models

Frontend Integration

Instructions for AI Agent

When working in the Cloudrave codebase:

1. **For auth changes:** Check `cloud-storage-backend/middleware/auth.js` and remember the `x-auth-token` header convention

2. **For upload flow changes:** Review the three-step process in `cloud-storage-backend/routes/files.js` and maintain S3 key format

3. **For frontend type changes:** Update `types.ts` and ensure all components using those types are updated

4. **For new features:** Check existing patterns in backend routes and frontend components before implementing

5. **For environment variables:** Add new secrets to backend only, never commit keys in frontend code

6. **When adding critical flows:** Create manual integration checks and document them (no automated tests currently exist)

Safety & Best Practices

Getting Help

If you need examples or clarification on any flow:

1. Specify which file or flow to expand

2. Reference the architecture section above

3. Check the key files list for implementation details