# techliondev/invistar architecture

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

- Interactive diagram: https://gitdiagram.com/techliondev/invistar
- Repository: https://github.com/techliondev/invistar

## Overview

##### Project type and purpose
- Full‑stack data management dashboard (CRUD for users, businesses, products, orders, invoices)
- Backend: PocketBase (Go‑based headless database + auth + file storage) with schema migrations
- Frontend: Next.js (App Router), TypeScript, React, UI component library, CSV import

##### File structure
- Top level:
– docker-compose.yaml
– backend/ (pocketbase, Dockerfiles, pb_migrations)
– frontend/ (Next.js app, Dockerfiles, components/, hooks/, lib/)
- backend/pb_migrations: sequential JS migration scripts for schema changes
- frontend/src/app: App Router folders for auth, landing, dashboard, resources (businesses, orders, products, settings)
- frontend/src/lib/api-service.ts + lib/pocketbase.ts: client wrappers for PocketBase API

##### README
- Minimal – only project name. Use file tree to infer purpose and tech stack.

##### Main components and their interactions
A. Client (Browser)
– Users access via browser over HTTPS
B. Frontend (Next.js container)
– SSR/CSR pages under /app
– Uses PocketBase JS SDK (lib/pocketbase.ts) and custom api-service for CRUD
C. Backend (PocketBase container)
– HTTP JSON API for auth, record management, file storage
– SQLite or built‑in DB + file storage on disk
– pb_migrations ensure DB schema is versioned
D. Data store
– Embedded database files + media folder managed by PocketBase
E. Container orchestration (Docker Compose)
– Defines two services: frontend, backend
F. Optional: CI/CD pipeline or developer machine

##### Architectural patterns and design principles
- Separation of concerns: UI vs. data layer vs. migrations
- Modular frontend: App Router (route groups), shared UI components, hooks, utils
- Containerization: consistent dev/prod via Dockerfiles (.dev and prod)
- Versioned schema migrations (pb_migrations directory)

##### Additional detail for this project
- Authentication flow: Next.js calls PocketBase auth endpoints (login, signup, verify, forgot).
- CSV import service: Frontend CSV importer → calls api-service → populates PocketBase collections.
- Modal-based CRUD UI as part of Next.js under “UI Components.”

##### Putting it all together
├── Frontend Container (Next.js)
└── Backend Container (PocketBase + migrations)
– From Browser to Frontend: labeled HTTPS
– From Frontend to Backend: labeled “PocketBase REST API”
– Call out env config (.env.example, next.config.ts, Dockerfiles) near each container

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["Browser / User"]:::actor

    subgraph "Docker Compose"
        subgraph "Frontend Container"
            FrontendContainer["Next.js Frontend"]:::frontend
            subgraph "App Router"
                AR["/src/app"]:::frontend
                subgraph "Auth Routes"
                    Login["login"]:::frontend
                    Signup["signup"]:::frontend
                    Verify["verify"]:::frontend
                    Forgot["forgot"]:::frontend
                end
                Landing["(landing)"]:::frontend
                subgraph "Dashboard & Resources"
                    Businesses["businesses"]:::frontend
                    Products["products"]:::frontend
                    Orders["orders"]:::frontend
                    Settings["settings"]:::frontend
                    DashboardPage["dashboard"]:::frontend
                end
            end
            UI["UI Components"]:::frontend
            HooksMQ["use-media-query.ts"]:::frontend
            HooksMobile["use-mobile.ts"]:::frontend
            LibPB["pocketbase.ts"]:::frontend
            LibAPI["api-service.ts"]:::frontend
            ConfigEnv[".env.example"]:::frontend
            ConfigNext["next.config.ts"]:::frontend
        end

        subgraph "Backend Container"
            BackendContainer["PocketBase Backend"]:::backend
            Migrations["pb_migrations"]:::backend
        end
    end

    DataStore["Database + File Storage"]:::persistence

    Browser -->|HTTPS| FrontendContainer
    FrontendContainer -->|PocketBase REST API| BackendContainer
    BackendContainer -->|"Read/Write DB & media"| DataStore

    click FrontendContainer "https://github.com/techliondev/invistar/tree/main/frontend/Dockerfile"
    click FrontendContainer "https://github.com/techliondev/invistar/blob/main/frontend/Dockerfile.dev"
    click FrontendContainer "https://github.com/techliondev/invistar/blob/main/docker-compose.yaml"
    click AR "https://github.com/techliondev/invistar/tree/main/frontend/src/app/"
    click Login "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(auth)/auth/login/"
    click Signup "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(auth)/auth/signup/"
    click Verify "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(auth)/auth/verify/"
    click Forgot "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(auth)/auth/forgot/"
    click Landing "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(landing)/"
    click Businesses "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(app)/app/businesses/"
    click Products "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(app)/app/products/"
    click Orders "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(app)/app/orders/"
    click Settings "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(app)/app/settings/"
    click DashboardPage "https://github.com/techliondev/invistar/tree/main/frontend/src/app/(app)/app/dashboard/"
    click UI "https://github.com/techliondev/invistar/tree/main/frontend/src/components/ui/"
    click HooksMQ "https://github.com/techliondev/invistar/blob/main/frontend/src/hooks/use-media-query.ts"
    click HooksMobile "https://github.com/techliondev/invistar/blob/main/frontend/src/hooks/use-mobile.ts"
    click LibPB "https://github.com/techliondev/invistar/blob/main/frontend/src/lib/pocketbase.ts"
    click LibAPI "https://github.com/techliondev/invistar/blob/main/frontend/src/lib/api-service.ts"
    click ConfigEnv "https://github.com/techliondev/invistar/blob/main/frontend/.env.example"
    click ConfigNext "https://github.com/techliondev/invistar/blob/main/frontend/next.config.ts"
    click BackendContainer "https://github.com/techliondev/invistar/tree/main/backend/Dockerfile"
    click BackendContainer "https://github.com/techliondev/invistar/blob/main/backend/Dockerfile.dev"
    click BackendContainer "https://github.com/techliondev/invistar/blob/main/docker-compose.yaml"
    click BackendContainer "https://github.com/techliondev/invistar/tree/main/backend/pocketbase"
    click BackendContainer "https://github.com/techliondev/invistar/blob/main/backend/pocketbase.exe"
    click Migrations "https://github.com/techliondev/invistar/tree/main/backend/pb_migrations/"

    classDef frontend fill:#ade8f4,stroke:#0077b6,color:#000
    classDef backend fill:#d0f4de,stroke:#2d6a4f,color:#000
    classDef persistence fill:#ffe5b4,stroke:#e09f3e,color:#000
    classDef actor fill:#cccccc,stroke:#888888,color:#000
```
