From bc868abbef82fa353952f498b098e594279a380e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=20Jurmanovi=C4=87?= <fjurma12@outlook.com>
Date: Sun, 6 Jul 2025 15:05:04 +0200
Subject: [PATCH] init docs

---
 01_Project_Vision.md        |  24 ++++++++
 02_Technology_Stack.md      |  46 ++++++++++++++++
 03_Architecture_Overview.md |  29 ++++++++++
 04_Project_Phases.md        |  78 ++++++++++++++++++++++++++
 DATABASE_SCHEMA.md          | 106 ++++++++++++++++++++++++++++++++++++
 README.md                   |  12 ++++
 6 files changed, 295 insertions(+)
 create mode 100644 01_Project_Vision.md
 create mode 100644 02_Technology_Stack.md
 create mode 100644 03_Architecture_Overview.md
 create mode 100644 04_Project_Phases.md
 create mode 100644 DATABASE_SCHEMA.md
 create mode 100644 README.md

diff --git a/01_Project_Vision.md b/01_Project_Vision.md
new file mode 100644
index 0000000..9ee9cd9
--- /dev/null
+++ b/01_Project_Vision.md
@@ -0,0 +1,24 @@
+1. Project Vision
+Project Title
+
+To be determined.
+Core Vision
+
+To create a high-performance, template-driven web platform designed for developers, project managers, and teams. The platform will be built on a robust and scalable architecture, separating concerns between a powerful backend and a fast, modern frontend.
+Key Features
+
+    Template-Driven Projects: Users can initialize new projects from a set of predefined "types," which configure the project's structure and default settings.
+
+    Backend-Driven Integrations: Users can connect their projects to third-party services (like GitHub) through secure, backend-managed integrations. This allows for the centralization of project-related data.
+
+    High-Performance User Experience: The frontend will be a highly responsive, server-rendered application, ensuring fast page loads and excellent SEO performance.
+
+    Future Extensibility: The long-term vision includes a frontend plugin system, allowing third-party developers to build and share new UI and functionality within the platform.
+
+Target Audience
+
+    Individual Developers
+
+    Development Teams
+
+    Project Managers
diff --git a/02_Technology_Stack.md b/02_Technology_Stack.md
new file mode 100644
index 0000000..3ac191f
--- /dev/null
+++ b/02_Technology_Stack.md
@@ -0,0 +1,46 @@
+2. Technology Stack
+Frontend
+
+    Framework: Next.js
+
+    Language: TypeScript
+
+    UI Library: React
+
+    Styling: Tailwind CSS
+
+    GraphQL Client: Apollo Client or urql
+
+    State Management: React Context API or Zustand
+
+Backend
+
+    Language: Go
+
+    Web Framework: Echo
+
+    API: GraphQL
+
+    Database: PostgreSQL
+
+    Authentication: JWTs managed by the Go backend
+
+API Communication
+
+    The Next.js frontend will communicate with the Go backend exclusively through the GraphQL API.
+
+Integrations
+
+    All third-party integrations (e.g., GitHub) will be handled securely on the Go backend. They will be architected as modular Go packages implementing a common interface.
+
+Deployment
+
+    Frontend (Next.js): Vercel
+
+    Backend (Go): Docker container deployed on a cloud provider (e.g., Google Cloud Run, AWS Fargate, DigitalOcean).
+
+Version Control
+
+    System: Git
+
+    Hosting: GitHub (using two separate repositories for frontend and backend).
diff --git a/03_Architecture_Overview.md b/03_Architecture_Overview.md
new file mode 100644
index 0000000..66d1b5c
--- /dev/null
+++ b/03_Architecture_Overview.md
@@ -0,0 +1,29 @@
+3. Architecture Overview
+Core Architecture: Decoupled Frontend & Backend
+
+The application is built on a modern, decoupled architecture:
+
+    Go Backend: A standalone service responsible for all core business logic. This includes user authentication, database interactions, and processing data from third-party integrations. It exposes all functionality through a single GraphQL API.
+
+    Next.js Frontend: A standalone service that consumes the Go backend's GraphQL API. It is responsible for the entire user interface and user experience. It leverages Next.js's Server-Side Rendering (SSR) capabilities to deliver fast, SEO-friendly pages.
+
+This separation of concerns allows for independent development, scaling, and maintenance of the frontend and backend.
+Backend Integrations Model
+
+All third-party integrations (e.g., connecting to GitHub) are handled exclusively by the Go backend.
+
+    Security: API keys and other secrets are stored securely on the server and are never exposed to the client-side.
+
+    Modularity: Each integration is built as a distinct Go package that implements a common Integration interface. This makes the system extensible, as new integrations can be added without modifying the core application logic.
+
+    Customization: Users with access to the backend codebase can "install" new integrations by adding the relevant package and recompiling the application.
+
+Future Vision: Frontend Plugin System
+
+For a future version (v2.0+), a frontend plugin system is envisioned. This is distinct from backend integrations.
+
+    Purpose: To allow developers to build and add new UI features and functionality directly into the frontend application.
+
+    Architecture: This will be achieved by running third-party JavaScript code in a sandboxed <iframe> for security.
+
+    SDK: A dedicated frontend "Plugin API" package (@your-app/plugin-sdk) will be developed. This will be the secure bridge allowing plugins to interact with the main application and render components in designated "slots."
diff --git a/04_Project_Phases.md b/04_Project_Phases.md
new file mode 100644
index 0000000..5576bd2
--- /dev/null
+++ b/04_Project_Phases.md
@@ -0,0 +1,78 @@
+4. Project Phases (Sequential Workflow)
+
+This project will be developed using a sequential workflow, focusing on completing the backend API before starting on the frontend implementation.
+Phase 1: Foundation & API Design (Week 1)
+
+    Focus: Setting up project structures and defining the API contract.
+
+    Tasks:
+
+        Initialize the Next.js and Go (Echo) projects in separate GitHub repositories.
+
+        Design the complete GraphQL schema. This schema is the definitive contract between the frontend and backend.
+
+        Design the modular Go interface for backend integrations.
+
+        Establish the PostgreSQL database connection in the Go project.
+
+        Set up the basic Next.js project with a GraphQL client.
+
+Phase 2: Core Backend Development (Weeks 2-5)
+
+    Focus: Building a complete and stable backend API. The frontend project is paused.
+
+    Tasks:
+
+        Implement the full PostgreSQL database schema.
+
+        Build the user authentication system using JWTs.
+
+        Write all GraphQL resolvers for the core features (users, projects, etc.).
+
+        Implement the backend logic for the integration system.
+
+        Build a proof-of-concept integration package (e.g., for GitHub).
+
+        Write comprehensive unit and integration tests for the API.
+
+Phase 3: Frontend Development & Connection (Weeks 6-8)
+
+    Focus: Building the user interface and connecting it to the now-stable backend API.
+
+    Tasks:
+
+        Connect the Next.js GraphQL client to the live Go backend endpoint.
+
+        Build all UI components and pages (login, dashboard, project views).
+
+        Implement the full client-side authentication flow (sending credentials, storing JWTs).
+
+        Write all necessary GraphQL queries and mutations to interact with the API.
+
+        Perform end-to-end testing of all user flows.
+
+Phase 4: Final Testing & Deployment (Week 9)
+
+    Focus: Preparing for launch and deploying both services.
+
+    Tasks:
+
+        Dockerize the Go application.
+
+        Set up a CI/CD pipeline and deploy the backend container to a cloud provider.
+
+        Configure the Next.js application for production and deploy it to Vercel.
+
+        Perform final integration and smoke testing on the live environment.
+
+Phase 5: Post-Launch & Maintenance (Ongoing)
+
+    Focus: Monitoring, iterating, and improving the live application.
+
+    Tasks:
+
+        Monitor the performance and logs of both services.
+
+        Gather user feedback for future improvements.
+
+        Plan and develop new backend integrations and frontend features.
diff --git a/DATABASE_SCHEMA.md b/DATABASE_SCHEMA.md
new file mode 100644
index 0000000..6acb9d0
--- /dev/null
+++ b/DATABASE_SCHEMA.md
@@ -0,0 +1,106 @@
+-- ##################################################################
+-- ## Core Entity Tables
+-- ##################################################################
+
+-- users: Stores individual user information and credentials.
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    full_name VARCHAR(255),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- roles: Defines the roles that can be assigned to users.
+CREATE TABLE roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- CHANGED: from SERIAL to UUID
+    name VARCHAR(50) UNIQUE NOT NULL -- e.g., 'admin', 'member', 'billing_manager'
+);
+
+-- permissions: Defines specific, granular permissions.
+CREATE TABLE permissions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- CHANGED: from SERIAL to UUID
+    name VARCHAR(100) UNIQUE NOT NULL -- e.g., 'project:create', 'task:delete', 'user:invite'
+);
+
+-- types: Stores the different "types" a project can be, now linked to a user.
+CREATE TABLE types (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- CHANGED: from SERIAL to UUID
+    user_id UUID REFERENCES users(id) ON DELETE SET NULL, -- ADDED: Makes types user-specific. Can be NULL for system default types.
+    name VARCHAR(100) NOT NULL,
+    description TEXT,
+    UNIQUE(user_id, name) -- A user can't have two types with the same name.
+);
+
+-- projects: The central table for projects.
+CREATE TABLE projects (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    owner_id UUID NOT NULL REFERENCES users(id),
+    type_id UUID NOT NULL REFERENCES types(id), -- CHANGED: from INT to UUID
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- tasks: Stores tasks, which belong to a project.
+CREATE TYPE task_status AS ENUM ('todo', 'in_progress', 'done', 'canceled');
+CREATE TYPE task_priority AS ENUM ('low', 'medium', 'high');
+
+CREATE TABLE tasks (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    title VARCHAR(255) NOT NULL,
+    description TEXT,
+    status task_status NOT NULL DEFAULT 'todo',
+    priority task_priority NOT NULL DEFAULT 'medium',
+    project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    due_date DATE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- integrations: Stores configuration for integrations linked to a project.
+CREATE TABLE integrations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    type VARCHAR(50) NOT NULL, -- e.g., 'github', 'slack'
+    config JSONB NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE(project_id, type)
+);
+
+
+-- ##################################################################
+-- ## Join Tables (for Relationships)
+-- ##################################################################
+
+-- user_roles: Assigns global roles to users.
+CREATE TABLE user_roles (
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE, -- CHANGED: from INT to UUID
+    PRIMARY KEY (user_id, role_id)
+);
+
+-- role_permissions: Assigns permissions to roles.
+CREATE TABLE role_permissions (
+    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE, -- CHANGED: from INT to UUID
+    permission_id UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE, -- CHANGED: from INT to UUID
+    PRIMARY KEY (role_id, permission_id)
+);
+
+-- project_members: Links users to the projects they are a part of.
+CREATE TABLE project_members (
+    project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES roles(id), -- CHANGED: from INT to UUID
+    PRIMARY KEY (project_id, user_id)
+);
+
+-- task_assignees: Assigns one or more users to a specific task.
+CREATE TABLE task_assignees (
+    task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    PRIMARY KEY (task_id, user_id)
+);
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b5db8f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,12 @@
+Project Plan Documentation
+
+This directory contains the complete project plan for the new web platform. The plan is broken down into several markdown files for clarity and organization.
+Document Structure
+
+    01_Project_Vision.md: A high-level overview of the project, its goals, and target audience.
+
+    02_Technology_Stack.md: A detailed list of the chosen technologies for the frontend, backend, and deployment.
+
+    03_Architecture_Overview.md: An explanation of the core architectural decisions, including the Next.js + Go structure, the backend-driven integration model, and the long-term vision for frontend plugins.
+
+    04_Project_Phases.md: The detailed, sequential project timeline, outlining each phase from foundation to deployment.
\ No newline at end of file