Palmr.

GitHub Architecture

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

other project 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
  • 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, and renames
  • 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. 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
  • 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

On this page