Untitled

A full-stack web application for managing floorplans, waypoints, and file uploads with a modern React frontend and Python backend.

Architecture

• Frontend: Next.js 15 with React 19, TypeScript, and Tailwind CSS
• Backend: Python with Litestar framework, PostgreSQL, and Redis
• Reverse Proxy: Caddy server for routing and static file serving

Features

• 🏗️ Project Management: Create and manage projects with user access control
• 📐 Floorplan Management: Upload and manage floorplan images
• 📍 Waypoint System: Track and manage waypoints within projects
• 📁 File Uploads: Handle file uploads with organized storage
• 👥 User Authentication: Secure user management with session handling
• 🌐 API-First Design: RESTful API with comprehensive endpoint coverage

Project Structure

├── frontend/           # Next.js React application
│   ├── src/
│   │   ├── app/       # App router pages
│   │   ├── components/ # Reusable UI components
│   │   ├── structures/ # Complex UI structures
│   │   └── styles/    # Global styles and themes
│   └── package.json
├── backend/           # Python Litestar API
│   ├── src/
│   │   ├── controllers/ # API route handlers
│   │   ├── models/     # Database models
│   │   └── utilities/  # Helper functions
│   ├── tests/         # Test suite
│   └── pyproject.toml
├── Caddyfile         # Reverse proxy configuration
└── start-*.sh        # Example development workflow scripts

Getting Started

Prerequisites

• Python ~3.12.0
• Node.js (latest LTS)
• PostgreSQL
• Redis
• Caddy (for reverse proxy)

Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Install dependencies:

   poetry install --with dev

3. Configure your database and Redis connections in backend.config.toml

4. Run the development server:

   litestar --app src:untitled run --debug --reload --host 127.0.0.1 --port 10000

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

Development Workflow

The included start-*.sh scripts demonstrate how to set up a complete development environment using tmux to manage multiple services simultaneously. These scripts show an example workflow for running:

• Backend API server (port 10000)
• Frontend development server (port 10001)
• Caddy reverse proxy
• Type checking (pyright)
• Text editor

You can use these as a reference to create your own development setup that suits your workflow and environment.

API Endpoints

The API is organized around these main resources:

• Projects: /api/projects/* - Project management
• Floorplans: /api/projects/{id}/floorplans/* - Floorplan CRUD operations
• Waypoints: /api/projects/{id}/floorplans/{id}/waypoints/* - Waypoint management
• Uploads: /api/projects/{id}/floorplans/{id}/waypoints/{id}/uploads/* - File upload handling per specific waypoint
• Users: /api/users/* - User management and authentication
• Sessions: /api/sessions/* - Session management

Static files are served at /media/* through Caddy.

Development

Code Quality

The project uses several tools for code quality:

Backend:

• Linting: ruff for Python code formatting and linting
• Type Checking: pyright for static type analysis
• Testing: pytest with async support and parallel execution

Frontend:

• Linting: ESLint with React and Next.js rules
• Type Checking: TypeScript with strict configuration
• Styling: Tailwind CSS with custom configurations

Testing

Run backend tests:

cd backend
pytest

Check test coverage:

cd backend
coverage run -m pytest
coverage html

Building for Production

Frontend:

cd frontend
npm run build
npm start

Backend:

cd backend
# Configure production settings in backend.config.toml
litestar --app src:untitled run --host 0.0.0.0 --port 10000

Configuration

• Backend Config: backend/backend.config.toml - Database, Redis, and security settings
• Frontend Config: frontend/next.config.mjs - Next.js configuration
• Proxy Config: Caddyfile - Reverse proxy and static file serving

License

This project is licensed under the MIT License - see the LICENSE file for details.