# LLM Guidance for the Time Tracking Project

This document provides guidance for Large Language Models (LLMs) working on the Time Tracking and Management System.

## File Locations

Here's a guide to finding information within the project:

**Documentation:**

-   **General Project Overview:** `docu/general_overview.md`
-   **Backend Architecture (Go):** `docu/backend_architecture.md`
-   **Frontend Architecture (Next.js):** `docu/frontend_architecture.md`
-   **Database Schema (PostgreSQL):** `docu/database_schema.md`
-   **Deployment and DevOps:** `docu/deployment_devops.md`
-   **Security and Privacy:** `docu/security_privacy.md`
-   **Extensibility and Integrations:** `docu/extensibility_integrations.md`
- **This LLM Guidance Document:** `docu/llm_guidance.md`
-   **Top Level Documentation Index:** `docu/README.md`

**Code (Conceptual - see architecture documents for details):**

-   **Backend (Go):**  (Refer to `docu/backend_architecture.md` for the conceptual structure.  Actual code structure may differ.)
    -   **Conceptual File Locations:**
        -   `backend-go/internal/domain/entities/`: Core domain entities (User, Company, Project, etc.)
        -   `backend-go/internal/domain/repositories/`: Interfaces for data access.
        -   `backend-go/internal/domain/services/`: Business logic implementation.
        -   `backend-go/internal/infrastructure/persistence/`: Database interactions (GORM).
        -   `backend-go/internal/interfaces/http/handlers/`: API endpoint handlers.
        -   `backend-go/internal/interfaces/http/middleware/`: Authentication and tenant isolation middleware.
    -   **Code Examples:**
        -   `docu/code_examples/gorm_entities.go`: Example GORM entity definitions.
        -   `docu/code_examples/fpgo_repository.go`: Example FPGO repository interface.
        -   `docu/code_examples/fpgo_service.go`: Example FPGO service implementation.
        -   `docu/code_examples/api_handler.go`: Example API handler.

-   **Frontend (Next.js):** (Refer to `docu/frontend_architecture.md` for the conceptual structure. Actual code structure may differ.)
    -   **Conceptual File Locations:**
        -   `frontend-nextjs/pages/`:  Application pages.
        -   `frontend-nextjs/components/`: Reusable UI components.
        -   `frontend-nextjs/lib/`:  API interaction and helper functions.
        -   `frontend-nextjs/types/`: TypeScript type definitions.
    -  **Code Examples:**
        - `docu/code_examples/react_component.tsx`: Example React component.

**Important Note about Code Examples:** The files in `docu/code_examples/` are for illustrative purposes *only*. They do *not* represent a runnable project structure.  Treat each file as an isolated example.  The package declarations within these files (e.g., `package entities`, `package repositories`, `package main`) are conceptual and should be interpreted in the context of the described architecture, *not* as a literal directory structure.  Do not attempt to run `go get` or similar commands based on these examples, as the necessary project structure and dependencies are not present.

## Rules and Guidelines

1.  **Clean Architecture:** Adhere to Clean Architecture principles. Separate business logic (domain) from infrastructure concerns (database, UI).
2.  **Domain-Driven Design (DDD):**  Use DDD concepts to model the domain accurately.
3.  **Multi-Tenancy:** Ensure all operations are scoped to the correct tenant (company). Use the `company_id` for data isolation.
4.  **FPGO and FPTS:**  Favor functional programming paradigms in both Go (FPGO) and TypeScript (FPTS).
5.  **Modularity:**  Keep code modular and well-organized.
6.  **Error Handling:** Implement robust error handling and validation.
7.  **Security:** Prioritize security.  Use JWT for authentication and RBAC for authorization.  Sanitize inputs to prevent injection attacks.
8.  **Testing:** Write unit and integration tests for all new code.
9. **Documentation**: Keep the documentation up to date.
10. **Conceptual Architecture**: The architecture files are a *concept*, not a final implementation.

## Ideas to Follow

-   **Small, Focused Modules:**  Break down tasks into small, well-defined modules.
-   **Descriptive Naming:** Use clear and descriptive names for variables, functions, and files.
-   **Comments:**  Add comments to explain complex logic.
-   **Consistency:** Maintain consistent coding style and patterns.
-   **Leverage Libraries:** Use existing libraries (FPGO, FPTS, GORM, Gin, Axios, etc.) where appropriate.
- **Ask for Clarification:** If unsure about any aspect of the project, use the `ask_followup_question` tool.
- **Visually Appealing Design:** (Especially for Claude models) Strive for a visually appealing and user-friendly interface. Consider using appropriate colors, layout, and components.
- **Prefer Replacements:** When making changes to existing files, favor the `replace_in_file` tool over `write_to_file` to minimize context usage and cost. Only use `write_to_file` for creating new files or making extensive, non-localized changes.

## Workflow for Limited Context

If you encounter context limitations or are instructed to work in smaller chunks, follow this workflow:

1.  **Request a Summary:** If needed, ask for a brief summary of the current task and relevant file content.
2.  **Plan in Chunks:** Divide the task into smaller, manageable sub-tasks.
3.  **Focus on One Chunk:** Work on one sub-task at a time.
4.  **Use `replace_in_file`:** Make targeted changes using `replace_in_file`.
5.  **Iterate:** Repeat steps 3 and 4 for each sub-task.
6.  **Provide Context Briefing:** When moving to a new chunk or file, provide a concise summary of the previous work and the current objective. This helps maintain context across multiple interactions.

## Code Organization and Style

- **Functional File Division:** Divide functionalities logically into separate files. This improves readability, maintainability, and helps manage context size.
- **Code Reusability:** Design code to be reusable and extensible. Anticipate future requirements and create components or functions that can be adapted for different purposes.
- **Common Sense:** Apply general good coding practices, even if they seem obvious. This includes things like:
    - Using meaningful variable and function names.
    - Adding comments to explain non-obvious logic.
    - Handling edge cases and potential errors.
    - Keeping functions and components concise and focused.
    - Following consistent indentation and formatting.