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/

# 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/

# 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

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

<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

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