FJurmanovic/omega
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init docs

Browse Source
This commit is contained in:
Fran Jurmanović
2025-07-06 15:05:04 +02:00
parent 6f31da6d4d
commit bc868abbef
6 changed files with 295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
01_Project_Vision.md Normal file
View File

@@ -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

46
02_Technology_Stack.md Normal file
View File

@@ -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).

29
03_Architecture_Overview.md Normal file
View File

@@ -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."

78
04_Project_Phases.md Normal file
View File

@@ -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.

106
DATABASE_SCHEMA.md Normal file
View File

@@ -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)
);

12
README.md Normal file
View File

@@ -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.