feat: Document project requirements and architectural design for a new multi-tenant project management system.

AI-Text/AI_Architect_Prompt.md

@@ -0,0 +1,151 @@
+ACT AS: Senior Full Stack Architect & DevOps Engineer
+
+CONTEXT & GOAL
+
+I am architecting and building a robust, self-hosted, SaaS-ready Project Management System deployed on my personal Oracle Cloud Free Tier infrastructure. The target environment is specifically the ARM64 (Ampere) architecture with 4 OCPUs and 24GB RAM.
+
+The system must solve the complexity of managing diverse project types (software, language learning, commercial, non-profit) through unlimited hierarchical nesting. Unlike flat project managers, this system treats hierarchy as a first-class citizen. The application must be multi-tenant by design, allowing different organizations or users to operate in complete data isolation within a shared application instance.
+
+Your task is to design the end-to-end architecture, define a high-performance database schema, and provide the initial production-grade code scaffolding. You must prioritize resource efficiency (due to the self-hosted nature) and scalability (due to the SaaS goal).
+
+INFRASTRUCTURE CONSTRAINTS & ENVIRONMENT
+
+Hardware Architecture: Oracle Cloud ARM64 (Ampere A1 Compute).
+
+Implication: All Docker images must be built for the linux/arm64 platform. You must ensure base images (e.g., node:alpine, postgres:alpine) are compatible.
+
+Orchestration Layer: K3s Cluster managed by Rancher.
+
+Implication: The application should be containerized and stateless to allow Kubernetes scaling. Resource limits (CPU/Memory) should be considered in the design.
+
+DevOps Ecosystem:
+
+VCS: Self-hosted Gitea.
+
+CI/CD: Gitea Actions (Runner deployed on K3s).
+
+Registry: Gitea Container Registry.
+
+Development: Coder (Remote dev environment running in the cluster).
+
+Implication: The CI/CD pipeline needs to handle multi-arch builds (likely using QEMU) if the runner architecture differs from the target, or native ARM builds if the runner is on the cluster.
+
+TECHNOLOGY STACK SPECIFICATIONS
+
+Backend Framework: NestJS (TypeScript).
+
+Reasoning: Strict modularity, Dependency Injection, and TypeScript support are required for long-term maintainability.
+
+ORM: TypeORM or Prisma (Select the one best suited for ltree raw query handling).
+
+Database: PostgreSQL (v14 or higher).
+
+Key Feature: Must utilize native extensions for hierarchy and JSON handling.
+
+Frontend Framework: React (Vite build tool) + Ant Design (UI Component Library).
+
+Visualization Engines:
+
+React Flow: For the interactive, node-based Mind Map view.
+
+Ant Design Tree: For the high-performance, lazy-loaded sidebar navigation.
+
+State Management: Zustand.
+
+Requirement: Must handle transient UI state (expanded nodes) separately from server state.
+
+CORE REQUIREMENTS & IMPLEMENTATION DETAILS
+
+1. Database Architecture (Hybrid Relational/Document)
+
+The database must perform performantly even with deep nesting (e.g., 50+ levels deep) and millions of nodes.
+
+Unlimited Hierarchy via LTREE:
+
+Enable the PostgreSQL ltree extension.
+
+Store the project path in a specific ltree column (e.g., TopLevel.SecondLevel.MyProject).
+
+Performance Constraint: Do NOT use recursive CTEs (Common Table Expressions) for subtree fetching, as they scale poorly. Use ltree operators (<@, @>) which utilize GIST indices for O(log n) retrieval speed.
+
+Flexibility via JSONB:
+
+Use a JSONB column named attributes to store polymorphic metadata.
+
+Example: A "Software" project stores {"repo_url": "...", "ci_status": "passing"}, while a "Language" project stores {"target_level": "C1", "daily_goal_minutes": 30}.
+
+Create a GIN index on this column to allow efficient searching across arbitrary keys (e.g., "Find all projects where repo_url is not null").
+
+Multi-Tenancy via RLS:
+
+Implement Row Level Security (RLS) natively in PostgreSQL.
+
+Every single table must include a tenant_id UUID column.
+
+Define database policies that strictly enforce tenant_id = current_setting('app.current_tenant'). This prevents accidental data leaks at the database engine level, acting as a safety net below the application logic.
+
+2. Backend Logic (NestJS)
+
+Modular Architecture: Organize the codebase into distinct domains: ProjectsModule, AuthModule (handling JWTs), TenantsModule, and WikiModule.
+
+Authentication & Context:
+
+Use Passport.js with JWT strategy.
+
+The JWT payload must contain the tenantId.
+
+Global Guard/Interceptor: Implement a mechanism that extracts the tenantId from the request and sets the PostgreSQL session variable (for RLS) or injects it into the ORM scope for every transaction.
+
+DTOs & Validation: Use class-validator to strictly validate the dynamic JSONB inputs to prevent arbitrary data injection, even in the "flexible" fields.
+
+3. Frontend Experience (React + AntD)
+
+Dual-View Synchronization:
+
+Sidebar (AntD Tree): Must support "Load on Demand". Do not fetch the entire tree at startup. Fetch children only when a node is expanded.
+
+Main View (React Flow): Visualizes the current context. If I click a folder in the Sidebar, the Mind Map should render that folder's direct children as nodes.
+
+Sync Strategy: Use Zustand to hold the "Active Project ID". Both components must subscribe to this ID. When the Sidebar selection changes, the Mind Map re-renders. When a Mind Map node is double-clicked (drilled down), the Sidebar must expand to reflect the new depth.
+
+i18n Architecture:
+
+Configure i18next with HTTP backend to load translation files (TR, EN, AR) lazily.
+
+Ensure RTL (Right-to-Left) support is fully functional for the Arabic interface, utilizing Ant Design's native ConfigProvider direction prop.
+
+DELIVERABLES REQUESTED
+
+Production-Ready Database Schema:
+
+Provide the full SQL DDL.
+
+Include CREATE EXTENSION commands.
+
+Include the specific CREATE INDEX commands for GIST (ltree) and GIN (jsonb) to ensure performance.
+
+Include the RLS Policy definitions.
+
+Backend Scaffolding (NestJS):
+
+Generate the ProjectsService specifically showing a method to "Move a project to a new parent". This involves updating the ltree path of the project and all its descendants. This is a complex operation; show the logic.
+
+Show the Guard/Middleware that handles Tenant Isolation.
+
+Frontend Component Strategy & State:
+
+Provide a code snippet demonstrating the Zustand store structure. It should handle expandedKeys, selectedKey, and projectData cache.
+
+Explain how to bridge the gap between AntD's tree data structure and React Flow's node/edge structure.
+
+CI/CD Pipeline (Gitea Actions):
+
+Create a .gitea/workflows/deploy.yaml.
+
+Critical: Configure docker/setup-buildx-action and docker/build-push-action.
+
+Explicitly set platforms: linux/amd64,linux/arm64 to ensure the image runs on your Oracle Ampere instance regardless of where the runner is hosted.
+
+TONE
+
+Be highly technical, precise, and production-oriented. Avoid generic "hello world" advice. Provide code snippets that fit the ARM64/K3s/NestJS ecosystem specifically. Assume the user is an experienced developer who needs architectural guidance, not basic tutorials.

AI-Text/Promtp.md

@@ -0,0 +1,107 @@
+Prompt: Project Brief for a Custom SaaS Project Management Application
+1. Executive Summary
+
+I need a custom SaaS (Software as a Service) application designed to manage a large and diverse portfolio of personal and professional projects. The core problem is a lack of a centralized system, leading to disorganization, forgotten projects, and inefficient prioritization. The application must feature a deep hierarchical structure, robust project management tools, and be deployable within my existing cloud infrastructure.
+2. The Problem Statement & My Needs
+
+I am currently managing numerous projects across many different categories:
+
+    Language learning
+
+    Software development
+
+    Community initiatives
+
+    Personal goals
+
+    Commercial ventures
+
+    Non-profit activities
+
+These projects vary in age, with some started a decade ago and others just a month ago. My primary challenges are:
+
+    Forgetting about projects: I lose track of ongoing or paused initiatives.
+
+    Mis-prioritization: I often assign high priority to low-impact projects.
+
+    Inefficient effort allocation: I spend too much time on projects that require less attention and vice-versa.
+
+    Lack of a single source of truth: My project information is scattered and disorganized.
+
+The goal of this application is to provide a single, clear dashboard where I can see, manage, prioritize, and track all my projects effectively.
+3. Core Functional Requirements
+
+The application should provide the following core features:
+
+    Centralized Project Dashboard: A main view that lists all projects, allowing for sorting, filtering, and searching.
+
+    Deep Hierarchical Structure (Parent/Child Projects): This is a critical requirement. I organize my thoughts and work hierarchically. The system must support deeply nested projects.
+
+        Example:
+
+            Level 1: Language Learning (Parent Project)
+
+            Level 2: English Learning (Child Project)
+
+            Level 3: Prepare for the YDS Exam (Grandchild Project)
+
+        The system should comfortably handle at least 7 levels of nesting.
+
+    Project Management Tools: For each project (at any level), I need to be able to:
+
+        Add detailed notes and descriptions.
+
+        Create a simple, integrated Wiki for documentation and knowledge management.
+
+        Set priorities (e.g., High, Medium, Low).
+
+        Assign categories or tags.
+
+        If it's a software project, provide a way to link to or manage a Git repository.
+
+    Methodology Inspiration: The system's design can draw inspiration from established international project management strategies and methodologies (e.g., GTD, Agile concepts, etc.). The concept could even be broader than "projects" and encompass "goals" or "initiatives."
+
+4. Non-Functional Requirements
+
+    Architecture: The application must be built as a multi-tenant SaaS platform. While I will be the first user, the architecture should allow other users to sign up, create their own accounts, and manage their own isolated set of projects.
+
+    Localization: The UI must be multi-lingual.
+
+        Initial Languages: Turkish, English, and Arabic.
+
+        Future Languages: The ability to add Chinese or other languages should be considered.
+
+        The localization system should be implemented using a standard, easily expandable format like JSON files.
+
+5. Technical & Deployment Environment
+
+The application must be designed to be deployed and operated within my existing infrastructure. This is a hard requirement.
+
+    Host Machine: An Oracle Free Tier VM (24GB RAM, 4 vCPUs).
+
+    Operating System: Rocky OS.
+
+    Orchestration: A K3s Kubernetes cluster is running on the machine.
+
+    Management: I use the Rancher UI (installed as a Docker container) to manage the K3s cluster.
+
+    Source Control: I use a self-hosted Gitea instance, installed via Helm on Rancher, for all my code.
+
+    Development Environment: I use Coder, running in the K3s cluster, which provides a browser-based VSCode environment for development. All git push/pull operations are done from Coder to Gitea.
+
+    CI/CD Pipeline: The entire CI/CD process is managed by Gitea Actions, using a Gitea runner deployed within my K3s cluster. The expected workflow is as follows:
+
+        A git push to the Gitea repository triggers a Gitea Actions workflow.
+
+        The workflow builds the application code into a Docker image.
+
+        The newly created image is pushed to the container registry integrated within my Gitea instance.
+
+        The final step in the workflow updates the relevant Kubernetes deployment/container in my cluster to use the new image, effectively deploying the change to production.
+
+The new application must be architected to fit seamlessly into this push-to-deploy workflow.
+6. Development Philosophy
+
+    Leverage Open-Source: I am not attached to the idea of building everything from scratch. The project should make extensive use of reliable open-source libraries, frameworks, and components for both the frontend and backend to accelerate development.
+
+    Urgency: I consider this project to be an urgent need to solve my current organizational challenges.