---
title: GitHub Architecture
icon: Github
---

import { File, Files, Folder } from "fumadocs-ui/components/files";

This guide provides a comprehensive overview of Palmr.'s GitHub repository structure, explaining how the different components are organized in the codebase. Understanding this architecture will help you navigate the repository, contribute effectively, and understand how the project is structured.

> **Overview:** Palmr. uses a monorepo architecture with clear separation between frontend, backend, and documentation components.

## Project structure

<Files>
  <Folder name="apps" defaultOpen>
    <Folder name="docs">
      <File name="all documentation files" />
    </Folder>
    <Folder name="server">
      <File name="all backend files" />
    </Folder>
    <Folder name="web">
      <File name="all frontend files" />
    </Folder>
  </Folder>
  <File name="other project files" />
</Files>

## Core components

### Frontend application (apps/web)

**Technology stack:**

- Next.js 15 (App Router)
- React 18
- TypeScript
- TailwindCSS
- shadcn/ui components
- next-intl for internationalization

Palmr.'s frontend is built with **Next.js 15**, using the App Router and Server Components for performance, scalability, and flexibility. The structure is modular and feature-based, keeping things easy to evolve as the product grows. UI logic runs on **React 18**, and **TypeScript** adds type safety that prevents a lot of silent bugs. Styles are handled with **TailwindCSS**, letting us build clean, responsive interfaces quickly. For components, we rely on **shadcn/ui**, a headless component library built with Radix UI and Tailwind, it's fast, accessible, and fully customizable.

Internationalization is handled by **next-intl**, which integrates perfectly with Next.js routing. It supports locale-aware routes, per-page translation loading, and plural rules, all without any extra client-side bloat. It's flexible, lightweight, and great for apps with multilingual audiences.

The frontend is organized with:

- A **components-based architecture** for modular UI
- **Custom hooks** to isolate logic and side effects
- A **route protection system** using session cookies and middleware
- A **file management interface** integrated with the backend
- **Folder support** for organizing files hierarchically
- A **reusable modal system** used for file actions, confirmations, and more
- **Dynamic, locale-aware routing** using next-intl

### Backend service (apps/server)

**Technology stack:**

- Fastify
- SQLite
- Filesystem storage (with S3-compatible object storage support)
- Prisma ORM

The backend is built on **Fastify**, a blazing-fast web framework for Node.js. It's lightweight, modular, and optimized for high performance. Every route is validated using JSON schema, which helps keep the API consistent and secure. Auth flows are built using JWTs stored in HTTP-only cookies, and everything from file uploads to token-based sharing goes through this layer.

Data is stored in **SQLite**, which handles user info, file metadata, session tokens, and more. For file storage, the system uses **filesystem storage** by default, keeping files organized in the local file system. The architecture also supports **S3-compatible object storage** as an alternative storage option for scalability. We use **Prisma** as our ORM to simplify database access, it gives us type-safe queries and easy-to-read code.

Key features include:

- **Authentication/authorization** with JWT + cookie sessions
- **File management logic** including uploads, deletes, renames, and folders
- **Storage operations** to handle file organization, usage tracking, and cleanup
- A **share system** that generates tokenized public file links
- Schema-based request validation for all endpoints
- Prisma models that keep the database logic predictable and type-safe

### Documentation (apps/docs)

**Technology stack:**

- Fumadocs
- MDX (Markdown + JSX)
- React-based components

The docs are built using **Fumadocs**, a modern documentation system built on top of Next.js. It uses **MDX**, so you can mix Markdown with interactive React components, perfect for developer tools and open-source projects. Pages are fast, versionable, and easy to customize. The goal is to keep the documentation as close to the codebase as possible, using shared components where needed and reusing UI patterns directly from the app.

It supports sidebar navigation, keyboard shortcuts, dark mode, and even interactive demos or UI previews. The file tree you see above, for example, is powered by a real React component from the docs.

- Built with **Fumadocs**, powered by Next.js
- Supports **MDX** and full React component embedding
- Ideal for technical docs and live code samples
- Styled using the same Tailwind setup from the main app

### Infrastructure

Palmr. is fully containerized using **Docker**, which means every service: frontend, backend, database, storage, runs in its own isolated environment. With `docker-compose`, the whole stack spins up locally with a single command. It's also easy to deploy to services like Fly.io, Render, or your own VPS.

Volumes are used to persist data locally, and containers are networked together so that all services can talk to each other securely.

- **Docker-first architecture** with all services containerized
- Configurable through `.env` and compose overrides
- Local volumes and named networks
- Easy to deploy and scale on any container-compatible infra

## Key features

### File management

Files are at the heart of Palmr. Users can upload files via the frontend, and they're stored directly in the filesystem. Users can also create folders to organize files. The backend handles metadata (name, size, type, ownership), and also handles deletion, renaming, and public sharing. Every file operation is tracked, and all actions can be scoped per user.

- Upload/download with instant feedback
- Create and organize files in folders
- File previews, type validation, and size limits
- Token-based sharing system
- Disk usage tracking by user

### User system

Authentication is done through secure JWTs, stored in HTTP-only cookies for safety. Signup and login flows are simple and fast, and user info is kept in sync across the frontend and backend.

- Cookie-based session management
- Role support and future admin access
- Profile updates and password reset flows
- Logged-in user state handled via custom hooks

### Storage system

The system uses **filesystem storage** for all file operations by default. It's simple, fast, and reliable for most use cases. The architecture also supports **S3-compatible object storage** as an alternative for users who need cloud storage or additional scalability. The backend tracks usage, handles cleanup of orphaned files, and ensures that every file on disk has a matching database record.

- Filesystem-based storage with organized directory structure
- Optional S3-compatible object storage support
- Upload validation and automatic cleanup
- Usage tracking and quotas (per user or global)
- Secure access to stored files with proper permissions

### Internationalization

Palmr. supports multiple languages using **next-intl**, which is deeply integrated into the routing system. It loads only the necessary translations per route, supports nested namespaces, and makes it easy to keep things organized even at scale.

- Per-locale localstorage (`en-US`, `pt-BR`, etc.)
- Translation loading by namespace/page
- Full pluralization and formatting support
- Easy translation management via JSON files
