time-tracker/docu/llm_guidance.md

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 models, 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.