# piotrkulpinski/openalternative architecture

> Architecture diagram of the GitHub repository piotrkulpinski/openalternative, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piotrkulpinski/openalternative
- Repository: https://github.com/piotrkulpinski/openalternative

## Overview

##### Project Overview and Type
- This is a full‐stack monorepo application built with Turborepo. Its main purpose is to serve as a community-driven directory of open source alternatives to proprietary software.
- The project is split into multiple “apps” (notably the Next.js web app under apps/web and the analysis tool under apps/analyzer) and shared “packages” (such as the database and GitHub integration modules).

##### Main Components
A. Frontend Application (apps/web):
– Represent the main Next.js application (using the Next.js App Router). This part includes:
- Pages & Routes: All the UI pages (including routes for home, blog, categories, alternatives, admin panel, etc.)
- Components: Reusable React components (web-specific and admin components)
- Contexts, Hooks, and Utilities: Essential for state management and helper functions.
- Configuration and assets (config, public files, content, styles, etc.)
B. Backend & API:
– Next.js server functions and API routes (under apps/web/app/api and apps/web/server) for handling business logic, authentication, and data fetching.
– Administration server (admin routes and APIs for managing alternatives, categories, tools, etc.)
C. Data Analysis Tool (apps/analyzer):
– A separate application for data analysis, including its own runtime setup (with environment variables, custom scripts, etc.), suggesting background or batch processing.
D. Shared Packages:
– Database Package (packages/db): Contains Prisma schema and client, representing the database layer (using Neon in production).
– GitHub Integration Package (packages/github): Modules for interacting with GitHub (likely for data ingestion or integration).
E. External Services and Integrations:
– Third-Party Services: Neon (Database), Plausible and PostHog (Analytics), Inngest (Background Jobs), AWS S3 (File storage), Stripe (Payments), and external service integrations for screenshots and newsletters.
– These services should be mapped as external systems that interact with the core applications via APIs or SDKs.

##### Connection and Relationships
– The Backend/API layer (server routes and API endpoints) that handle data processing.
– The Shared Database package that acts as the data storage layer.
- For the Analyzer tool, show its role in processing data and possibly interacting with the database and external services (job schedulers, etc.).
- The shared packages should be shown as a library layer that both apps (web and analyzer) depend on.

##### Architectural Patterns and Design Principles
- Modularization inherent in the monorepo architecture, with Turborepo orchestrating dependencies and tasks.
- Separation of concerns:
- UI/Presentation Layer (React components, pages)
- Business Logic (server actions, API routes, and services)
- Data Layer (Prisma, DB utilities)
- External Integration Layer (third-party APIs).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Apps Subgraph
    subgraph "Apps"
        subgraph "Web App (Next.js)"
            wPages["Pages & Routes"]:::app1
            wComponents["Components"]:::app1
            wContexts["Contexts, Hooks & Config"]:::app1
            wAPI["API Routes"]:::backend
            wServer["Server Functions"]:::backend
        end
        analyzer["Analyzer Tool"]:::analyzer
    end

    %% Shared Packages Subgraph
    subgraph "Shared Packages"
        db["Database (Prisma + Neon)"]:::package
        gh["GitHub Integration Package"]:::package
    end

    %% External Services Subgraph
    subgraph "External Services"
        ext["Third-Party Services (Neon, Plausible, PostHog, Stripe, AWS S3, Inngest)"]:::external
    end

    %% Connections within Web App
    wPages -->|"fetches"| wAPI
    wPages -->|"calls"| wServer
    wComponents --- wPages
    wContexts --- wPages

    %% Connections from Web App to Shared Packages
    wAPI -->|"queries"| db
    wAPI -->|"integrates"| gh

    %% Connections from Analyzer Tool to Shared Packages
    analyzer -->|"queries"| db
    analyzer -->|"integrates"| gh

    %% Connections to External Services
    wAPI -->|"communicates"| ext
    analyzer -->|"sendsJobs"| ext

    %% Click Events
    click wPages "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/app"
    click wComponents "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/components"
    click wContexts "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/contexts"
    click wAPI "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/app/api"
    click wServer "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/server"
    click analyzer "https://github.com/piotrkulpinski/openalternative/tree/main/apps/analyzer"
    click db "https://github.com/piotrkulpinski/openalternative/tree/main/packages/db"
    click gh "https://github.com/piotrkulpinski/openalternative/tree/main/packages/github"
    click ext "https://github.com/piotrkulpinski/openalternative/tree/main/apps/web/services"

    %% Styles
    classDef app1 fill:#bbdefb,stroke:#0d47a1,stroke-width:2px
    classDef backend fill:#ef9a9a,stroke:#c62828,stroke-width:2px
    classDef analyzer fill:#d1c4e9,stroke:#512da8,stroke-width:2px
    classDef package fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef external fill:#ffe082,stroke:#ff6f00,stroke-width:2px
```
