mirror of
https://github.com/kyantech/Palmr.git
synced 2025-10-23 06:11:58 +00:00
4fb7007db2
- Removed the outdated .eslintrc.json file and replaced it with a new eslint.config.mjs file for better configuration management. - Added .prettierrc.json to enforce consistent code formatting and included a .prettierignore file to exclude specific directories from formatting. - Updated components.json to streamline alias definitions and ensure proper icon library usage. - Enhanced package.json with new linting, formatting, and validation scripts to improve development workflow. - Made various formatting adjustments across multiple files for consistency and clarity.
145 lines
6.6 KiB
Plaintext
145 lines
6.6 KiB
Plaintext
---
|
||
title: </> Github Architecture
|
||
---
|
||
|
||
import { File, Files, Folder } from "fumadocs-ui/components/files";
|
||
|
||
## 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
|
||
- 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
|
||
- PostgreSQL
|
||
- MinIO (S3-compatible)
|
||
- 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 **PostgreSQL**, which handles user info, file metadata, session tokens, and more. For actual file storage, we use **MinIO**, a fast, S3-compatible object store that’s self-hosted and super scalable. It’s perfect for keeping user files isolated and safe. 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 bucket creation, 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 streamed directly to MinIO. 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
|
||
|
||
MinIO is used for all file storage. It’s fast, lightweight, and fully S3-compatible which means it can scale easily and integrates with tons of other tools. The backend tracks usage, handles cleanup of orphaned files, and ensures that every file on disk has a matching database record.
|
||
|
||
- S3-compatible object storage via MinIO
|
||
- Upload validation and automatic cleanup
|
||
- Usage tracking and quotas (per user or global)
|
||
- Secure access to stored files with signed URLs
|
||
|
||
### 🌐 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
|