Skip to content

GEMINI.md

Latest commit

 

History

History
144 lines (94 loc) · 5.14 KB

GEMINI.md

File metadata and controls

144 lines (94 loc) · 5.14 KB

🤖 GEMINI.md - AI Agent & Developer Guide

This document serves as a comprehensive guide for AI Agents and developers working on the Google Cloud Creative Studio Platform project. It outlines the architecture, setup, development workflow, and strict guidelines to ensure code quality and consistency.

🏗️ System Architecture

Creative Studio follows a Modular, Feature-Driven Architecture (inspired by Hexagonal Architecture).

  • Structure: Code is organized by feature domain (e.g., /images, /users) rather than technical layer.
  • Cohesion: All code for a single feature is co-located (controllers, services, DTOs).
  • Coupling: Modules interact through well-defined interfaces.

🚀 Bootstrapping (Docker Compose)

The standard development environment uses Docker Compose.

1. Prerequisites

  • gcloud CLI: Authenticated and project set.
  • Docker & Docker Compose
  • uv: Fast Python package installer.

2. Environment Configuration

  • Backend (backend/.env):
    • Set ENVIRONMENT="local"
    • Set USE_CLOUD_SQL_AUTH_PROXY=false (uses local Postgres container).
    • Set isLocal = True (critical for local auth).
  • Frontend (frontend/src/environments/environment.development.ts):
    • Set isLocal: true
    • Configure Firebase credentials.

3. Starting the Application

From the root directory:

# Authenticate gcloud
gcloud auth application-default login

# Start containers
docker compose up --build

4. Seeding Initial Data

If the database is fresh, run the bootstrap script to seed templates:

docker exec -t creative-studio-backend sh -c "PYTHONPATH=/app uv run python -m bootstrap.bootstrap"

🛠️ Development Workflow

Backend (Python)

  • Hot Reload: Enabled by default in Docker.
  • Package Management: Uses uv and pyproject.toml.
  • Running Scripts: ALWAYS use docker compose to run Python scripts (e.g., docker exec ...).

Frontend (Angular)

  • Reactivity: Strictly use Angular Signals for state management and computed values.
  • API Calls: Implement API calls in a Service. DO NOT use fetch or HttpClient directly inside components.

🛡️ Code Quality & Linters (Pre-commit)

We use a fully containerized pre-commit pipeline. DO NOT run linters locally on your host machine.

1. Setup Git Hook

Run once from the root:

cp pre-commit-hook.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

2. Manual Run

To format and lint the entire repository at once:

docker compose run --rm pre-commit run --all-files

3. Linters Used

  • Backend: black (formatting), pylint (linting).
  • Frontend: gts (ESLint + Prettier).
  • License: addlicense (adds headers).

🧪 Running Tests

Backend (Python)

We use pytest and pytest-cov.

Important

PR Requirement: You must achieve at least 80% code coverage across all src/ files.

Verify Coverage Locally:

cd backend
uv run pytest tests -v --cov=src --cov-fail-under=80

Run Specific Tests:

uv run pytest tests/users -v

📜 AI Agent Guidelines & Rules

To maintain a pristine codebase, AI Agents MUST follow these rules:

  1. Docker Enforcement: Always use docker compose or docker exec to run Python scripts or commands that interact with the app environment. Always check if the docker containers are running correctly and in case of finding any errors solve them until the container starts successfully.
  2. Precise Edits: When editing files, ensure you replace only the target content. DO NOT append garbage lines or duplicate code.
  3. Reactivity First: In Angular, leverage Signals for computed state to avoid reactivity bugs.
  4. Error Handling: Always wrap async/stream operations in try/catch and log errors appropriately.
  5. Format Before Commit: Always ensure the code is formatted by using the prechecks leveraging automation for code quality before finishing execution.
  6. Commiting Changes: Never commit changes, just leave the changes in the files for the user to review and commit.
  7. Testing: Always run the tests and verify the coverage is above 80% before finishing execution, if it fails or coverage is below 80%, fix it, add the missing tests and run the tests again until it passes and coverage is above 80%.
  8. Linting: Always run the linter and verify the code is clean before finishing execution, if it fails, fix it and run the pre-commit hook again.
  9. Documentation: Always update the documentation when making changes to the code, even this file if needed.
  10. Seniority: Act as a Senior Software Engineer with 10+ years of experience in software development.
  11. Code Review: Always review the code before finishing execution, if it fails, fix it and run the pre-commit hook again.
  12. Security: Always review the code for security vulnerabilities and fix them if found.
  13. Isolation: Always work in isolation, do not modify files outside the scope of the task. Work with docker containers, do not run any gcloud commands locally nor modify any cloud resources.