Build_God/AGENTS.md

# AGENTS.md - Build God Project

This document provides guidelines for agentic coding agents working on this repository.

## Project Overview

Build God is a full-stack application with:
- **Backend**: ASP.NET Core 8.0 Web API (C#)
- **Frontend**: Vue 3 + TypeScript + Vite + Element Plus

---

## 1. Build, Lint, and Test Commands

### Backend (.NET API)

Located in: `BuildGod_Api/`

```bash
# Build the solution
dotnet build BuildGod_Api.sln

# Run the API (from BuildGod_Api directory)
dotnet run --project Build_God_Api/Build_God_Api.csproj

# Build and run with Docker
docker build -t build-god-api BuildGod_Api/
docker run -p 5091:80 build-god-api
```

**Note**: No test framework is currently configured for the backend.

### Frontend (Vue 3)

Located in: `Build_God_Admin_Frontend/Frontend/`

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type-check only
npm run type-check

# Preview production build
npm run preview
```

**Running a single test**: No tests are currently configured.

---

## 2. Code Style Guidelines

### Backend (.NET/C#)

#### General Conventions
- Use **file-scoped namespaces** (`namespace Build_God_Api.Controllers;`)
- Enable **nullable reference types** (`<Nullable>enable</Nullable>`)
- Use **primary constructors** for dependency injection
- Use **async/await** for all I/O operations

#### Naming Conventions
- **Types/Classes**: PascalCase (`AccountController`, `AccountService`)
- **Methods**: PascalCase (`GetAccount`, `Register`)
- **Properties**: PascalCase (`UserName`, `Email`)
- **Local variables**: camelCase (`accountId`, `existingAccount`)
- **Parameters**: camelCase (`accountName`, `emailAddress`)
- **Interfaces**: Prefix with `I` (`IAccountService`, `ICurrentUserService`)

#### Project Structure
```
Controllers/     # API endpoints
Services/        # Business logic (interface + implementation)
DB/              # Database entities/models
```

#### Error Handling
- Return `BadRequest("error message")` for validation errors
- Return `Ok(result)` for successful operations
- Use try-catch with logging for operations that may fail
- Use `ILogger<T>` for logging

#### Dependency Injection
```csharp
public class AccountController(IAccountService service) : ControllerBase
{
    private readonly IAccountService _service = service;
    // ...
}
```

#### Route Conventions
- Use `[Route("api/god/[controller]")]`
- Use `[ApiController]` attribute
- Use HTTP method attributes: `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`

---

### Frontend (Vue 3 + TypeScript)

#### General Conventions
- Use **Composition API** with `<script setup lang="ts">`
- Enable **strict TypeScript** mode
- Use **path aliases**: `@/` maps to `src/`

#### Naming Conventions
- **Components**: PascalCase (`LoginView.vue`, `Sidebar.vue`)
- **Variables/functions**: camelCase (`handleLogin`, `userName`)
- **Types/Interfaces**: PascalCase (`LoginRequest`, `User`)
- **Constants**: UPPER_SNAKE_CASE (or camelCase for simple constants)
- **File names**: kebab-case for utilities, PascalCase for components

#### Project Structure
```
src/
  api/           # API calls
  components/    # Reusable components
  views/         # Page components (often in subdirectories)
  stores/        # Pinia stores
  router/        # Vue Router configuration
```

#### Imports
- Use `@/` alias for src-relative imports: `import { useAuthStore } from '@/stores/auth'`
- Group imports: external libs → internal imports → types
- Use absolute imports for internal modules

#### TypeScript Guidelines
- Always define types/interfaces for API responses and request payloads
- Use `ref<T>` and `computed<T>` for reactive state
- Avoid `any` - use `unknown` or proper types

#### Vue Component Patterns
```vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useRouter } from 'vue-router'
import { ElMessage } from 'element-plus'

const router = useRouter()
const loading = ref(false)
// ...
</script>

<template>
  <!-- Use Element Plus components -->
</template>

<style scoped lang="css">
/* Component styles */
</style>
```

#### Pinia Store Pattern
```typescript
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useAuthStore = defineStore('auth', () => {
  const token = ref('')
  const isAuthenticated = computed(() => !!token.value)

  const login = async () => { /* ... */ }

  return { token, isAuthenticated, login }
})
```

#### UI Library (Element Plus)
- Use Element Plus components: `ElButton`, `ElInput`, `ElTable`, etc.
- Use `ElMessage` for notifications
- Use `ElMessageBox` for confirmations
- Follow Element Plus prop naming conventions

#### Error Handling
- Use try-catch with async/await
- Show errors with `ElMessage.error()`
- Handle 401 (unauthorized) by redirecting to login

---

## 3. API Integration

### Backend API Base URL
- Development: `http://localhost:5091/api/god/`
- Routes follow pattern: `api/god/{entity}` (e.g., `api/god/account/login`)

### Authentication
- Use JWT Bearer tokens
- Store token in `localStorage` as `auth_token`
- Include in requests: `Authorization: Bearer {token}`

### Common Endpoints
- POST `/api/god/account/register` - Register new account
- POST `/api/god/account/login` - User login
- POST `/api/god/account/login/admin` - Admin login (use: name="admin", password="build_god.123")

---

## 4. Development Workflow

1. **Start Backend**: Run `dotnet run` in `BuildGod_Api/`
2. **Start Frontend**: Run `npm run dev` in `Build_God_Admin_Frontend/Frontend/`
3. **Access**: Frontend runs on `http://localhost:5173` by default

---

## 5. Adding New Features

### Backend
1. Create model in `DB/` folder (extend `BaseEntity`)
2. Create service interface in `Services/`
3. Implement service in `Services/`
4. Create controller in `Controllers/`
5. Register service in `Program.cs`

### Frontend
1. Create API module in `src/api/`
2. Add Pinia store in `src/stores/` (if needed)
3. Create view component in `src/views/`
4. Add route in `src/router/index.ts`

---

## 6. Important Notes

- The admin login credentials are hardcoded: `admin` / `build_god.123`
- Backend runs on port 5091
- Frontend uses Vite proxy for API calls (configured in `vite.config.ts`)
- Use `npm run type-check` before committing to catch TypeScript errors
- Always use `await` with async operations - never ignore promises