How charly-js/colgit works
Project Overview
• That the project is a full-stack application built with Next.js 13 (using the App Router), React 18, and TypeScript on the frontend, and Next.js API routes on the backend.
• The platform supports version control, project management, real-time collaboration, and an AI assistant for code debugging.
• The underlying architectural style is hexagonal, which divides the system into domain (business logic), ports (interfaces), and adapters (implementations).
• User Interface Layer:
• “app” directory: Contains Next.js pages for different routes like activity, admin dashboard, calendar, login, profile, etc.
• “components”: A large set of reusable UI elements (e.g., navigation, chat, repository view, admin panels).
• “public”: Contains static assets like logos.
• Domain Layer:
• “domain” directory: Holds business entities for activity, admin, AI assistant, authentication, collaborators, and repository management. This is the heart of your business logic.
• Application Services:
• “services”: Contains service files (activity.service.ts, admin.service.ts, etc.) that orchestrate domain operations.
• Adapters (Infrastructure Layer):
• “adapters”: Implements concrete adapters for interfacing with various external systems (activity, admin, AI, auth, collaborator, repository), following the port and adapter pattern.
• Database Component:
• “col-git (db)”: Contains configuration, migrations, seeds, and other database-related setup. It’s distinct from the main application code and represents the persistence/storage layer.
• Additional Modules (Utilities & Configuration):
• “lib”, “utils”, “hooks”, and “docs”: Provide supporting utilities, UI hooks, and configuration setups (such as theme, translations).
Relationships and Interactions
• Surround the domain with the ‘ports’ layer (conceptually) that includes interfaces used by both the UI and infrastructure layers.
• Adapters connected to the ports:
• Adapters (in the “adapters” folder) provide external integrations for authentication, repository management, AI interactions, etc.
• Communication flows:
• UI components (from “app” and “components”) invoke actions on the backend APIs.
• API routes (in “app/api”) act as controllers that call the underlying services.
• Services execute business logic in the domain and interact with the adapters, which then read/write to the database (“col-git (db)”).
• External integrations (e.g., OpenAI for AI-assisted debugging) can also be marked as external systems interfaced through specific adapters.
Architectural Patterns and Important Design Principles
• Core Domain: “domain” logic.
• Ports: Abstract interfaces (these might not be a physical folder but are conceptually implemented by the adapters).
• Adapters: “adapters” directory provides concrete implementations bridging external services and frameworks.
• Separation between presentation (UI – “app” and “components”), business logic (domain and services), and persistence (database folder “col-git (db)”).
• Mention that the project leverages TypeScript and follows a modular design so that responsibilities are clearly demarcated.
Diagramming Tools & Detail Level
• Every component is clearly labeled.
• Use annotations to emphasize key interactions such as authentication flows, AI assistance integration, and repository management processes.