# Sharenet Project Index ## Project Overview Sharenet is a full-stack application for managing users and products, built with Rust (backend) and Next.js (frontend). It demonstrates clean architecture principles with multiple interface options and configurable storage backends. ## Architecture ### Backend Architecture (Clean Architecture) The backend follows clean architecture principles with clear separation of concerns: ``` ┌─────────────────────────────────────────────────────────────┐ │ Interface Layer │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ API │ │ CLI │ │ TUI │ │ │ │ (Axum) │ │ (Clap) │ │ (Ratatui) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ Application Layer │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Service/UseCase Layer │ │ │ │ - UserService │ │ │ │ - ProductService │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ Domain Layer │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ - User Entity │ │ │ │ - Product Entity │ │ │ │ - Repository Traits │ │ │ │ - Domain Errors │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ Infrastructure Layer │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Memory │ │ PostgreSQL │ │ │ │ Repository │ │ Repository │ │ │ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## Project Structure ``` sharenet/ ├── backend/ # Rust backend │ ├── Cargo.toml # Workspace configuration │ ├── README.md # Backend documentation │ ├── crates/ # Backend modules │ │ ├── domain/ # Domain entities and traits │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # Core domain logic │ │ ├── application/ # Application services │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # Use case implementations │ │ ├── api/ # HTTP API (Axum) │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # REST API endpoints │ │ ├── cli/ # CLI interface (Clap) │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # Command-line interface │ │ ├── tui/ # TUI interface (Ratatui) │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # Text user interface │ │ ├── memory/ # In-memory storage │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # Memory repository implementation │ │ ├── postgres/ # PostgreSQL storage │ │ │ ├── Cargo.toml │ │ │ └── src/lib.rs # PostgreSQL repository implementation │ │ ├── sharenet-api-memory/ # API binary (memory) │ │ │ ├── Cargo.toml │ │ │ └── src/main.rs # API entry point │ │ ├── sharenet-api-postgres/ # API binary (PostgreSQL) │ │ │ ├── Cargo.toml │ │ │ └── src/main.rs # API entry point │ │ ├── sharenet-cli-memory/ # CLI binary (memory) │ │ │ ├── Cargo.toml │ │ │ └── src/main.rs # CLI entry point │ │ ├── sharenet-cli-postgres/ # CLI binary (PostgreSQL) │ │ │ ├── Cargo.toml │ │ │ └── src/main.rs # CLI entry point │ │ ├── sharenet-tui-memory/ # TUI binary (memory) │ │ │ ├── Cargo.toml │ │ │ └── src/main.rs # TUI entry point │ │ └── sharenet-tui-postgres/ # TUI binary (PostgreSQL) │ │ ├── Cargo.toml │ │ └── src/main.rs # TUI entry point │ ├── migrations/ # Database migrations │ │ └── 20240101000000_create_tables.sql │ └── config/ # Configuration files │ ├── api-memory.env # API with memory storage │ ├── api-postgres.env # API with PostgreSQL │ ├── cli-memory.env # CLI with memory storage │ ├── cli-postgres.env # CLI with PostgreSQL │ ├── tui-memory.env # TUI with memory storage │ └── tui-postgres.env # TUI with PostgreSQL ├── frontend/ # Next.js frontend │ ├── package.json # Frontend dependencies │ ├── README.md # Frontend documentation │ ├── src/ # Source code │ │ ├── app/ # Next.js app directory │ │ │ ├── layout.tsx # Root layout │ │ │ ├── page.tsx # Dashboard page │ │ │ ├── users/ # Users pages │ │ │ │ └── page.tsx # Users management │ │ │ └── products/ # Products pages │ │ │ └── page.tsx # Products management │ │ ├── components/ # React components │ │ │ └── ui/ # shadcn/ui components │ │ │ ├── button.tsx # Button component │ │ │ ├── card.tsx # Card component │ │ │ ├── dialog.tsx # Dialog component │ │ │ ├── form.tsx # Form component │ │ │ ├── input.tsx # Input component │ │ │ ├── label.tsx # Label component │ │ │ └── table.tsx # Table component │ │ └── lib/ # Utility functions │ │ ├── api.ts # API client │ │ └── utils.ts # Utility functions │ ├── public/ # Static assets │ │ ├── file.svg # File icon │ │ ├── globe.svg # Globe icon │ │ ├── next.svg # Next.js logo │ │ ├── vercel.svg # Vercel logo │ │ └── window.svg # Window icon │ ├── components.json # shadcn/ui configuration │ ├── next.config.ts # Next.js configuration │ ├── postcss.config.mjs # PostCSS configuration │ ├── tailwind.config.js # Tailwind CSS configuration │ └── tsconfig.json # TypeScript configuration ├── README.md # Project documentation ├── LICENSE.md # Project license └── .gitignore # Git ignore rules ``` ## Key Components ### Domain Layer (`backend/crates/domain/`) **Core Entities:** - `User`: User entity with id, username, email, timestamps - `Product`: Product entity with id, name, description, timestamps - `CreateUser`/`UpdateUser`: DTOs for user operations - `CreateProduct`/`UpdateProduct`: DTOs for product operations **Traits:** - `Entity`: Base trait for domain entities - `Repository`: Generic repository trait for CRUD operations **Error Handling:** - `DomainError`: Domain-specific error types (NotFound, InvalidInput, Internal) ### Application Layer (`backend/crates/application/`) **Services:** - `Service`: Generic service implementation - `UseCase`: Use case trait for business operations - `Repository`: Repository trait for data access **Features:** - Generic implementations for easy extension - Static dispatch with generic traits - Comprehensive test coverage with mock repositories ### Infrastructure Layer #### Memory Repository (`backend/crates/memory/`) - In-memory storage using `HashMap` and `RwLock` - Suitable for development and testing - No external dependencies #### PostgreSQL Repository (`backend/crates/postgres/`) - SQLx-based PostgreSQL implementation - Connection pooling with PgPool - Prepared query caching for performance - Migration support ### Interface Layer #### HTTP API (`backend/crates/api/`) - **Framework**: Axum - **Features**: - RESTful endpoints for users and products - CORS support - Request/response logging - JSON serialization/deserialization - **Endpoints**: - `POST /users` - Create user - `GET /users/:id` - Get user by ID - `GET /users` - List all users - `PUT /users/:id` - Update user - `DELETE /users/:id` - Delete user - `POST /products` - Create product - `GET /products/:id` - Get product by ID - `GET /products` - List all products - `PUT /products/:id` - Update product - `DELETE /products/:id` - Delete product #### CLI (`backend/crates/cli/`) - **Framework**: Clap - **Features**: - Subcommand-based interface - User and product management commands - JSON output support - **Commands**: - `user create --username --email ` - `user get --id ` - `user list` - `user update --id [--username ] [--email ]` - `user delete --id ` - `product create --name --description ` - `product get --id ` - `product list` - `product update --id [--name ] [--description ]` - `product delete --id ` #### TUI (`backend/crates/tui/`) - **Framework**: Ratatui - **Features**: - Interactive terminal interface - Table-based data display - Form-based data entry - Navigation between users and products ### Frontend (`frontend/`) #### Technology Stack - **Framework**: Next.js 15.3.3 - **Language**: TypeScript - **UI Library**: React 19 - **Styling**: Tailwind CSS - **Components**: shadcn/ui - **Form Handling**: React Hook Form with Zod validation - **HTTP Client**: Axios #### Key Features - **Dashboard**: Overview page with navigation to users and products - **Users Management**: - View all users in a table - Create new users via dialog - Edit existing users - Delete users with confirmation - **Products Management**: - View all products in a table - Create new products via dialog - Edit existing products - Delete products with confirmation #### API Integration - **Base URL**: `http://127.0.0.1:3000` - **Client**: Axios-based API client in `src/lib/api.ts` - **Type Safety**: Full TypeScript interfaces for API responses ## Database Schema ### Users Table ```sql CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), username TEXT NOT NULL, email TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP ); ``` ### Products Table ```sql CREATE TABLE products ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT NOT NULL, description TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP ); ``` ## Configuration ### Backend Configuration Configuration files are located in `backend/config/`: - `api-memory.env` - API server with in-memory storage - `api-postgres.env` - API server with PostgreSQL storage - `cli-memory.env` - CLI with in-memory storage - `cli-postgres.env` - CLI with PostgreSQL storage - `tui-memory.env` - TUI with in-memory storage - `tui-postgres.env` - TUI with PostgreSQL storage ### Environment Variables - `SERVER_ADDR` - Server address (default: 127.0.0.1:3000) - `DATABASE_URL` - PostgreSQL connection string - `RUST_LOG` - Logging level (default: info) ## Development Workflow ### Backend Development 1. **Setup**: Install Rust and SQLx CLI 2. **Database**: Create database and run migrations 3. **Build**: `cargo build` 4. **Run**: Choose appropriate binary for your use case 5. **Test**: `cargo test` ### Frontend Development 1. **Setup**: Install Node.js and npm 2. **Install**: `npm install` 3. **Run**: `npm run dev` 4. **Build**: `npm run build` ### Running the Full Stack 1. Start backend: `cargo run --bin sharenet-api-postgres` 2. Start frontend: `cd frontend && npm run dev` 3. Access web interface at `http://localhost:3000` ## Testing ### Backend Testing - **Unit Tests**: Each crate has comprehensive unit tests - **Integration Tests**: Repository implementations are tested - **Mock Testing**: Mock repositories for isolated testing ### Frontend Testing - **Component Testing**: Individual React components - **Integration Testing**: API integration and user flows - **E2E Testing**: Full application workflows ## Deployment ### Backend Deployment - **Docker**: Containerized deployment - **Binary**: Standalone executables - **Database**: PostgreSQL with connection pooling ### Frontend Deployment - **Vercel**: Optimized for Next.js - **Static Export**: Can be deployed to any static hosting - **Docker**: Containerized deployment ## Performance Considerations ### Backend - **Connection Pooling**: PostgreSQL connection pooling - **Query Caching**: SQLx prepared query caching - **Async/Await**: Non-blocking I/O operations - **Generic Implementations**: Zero-cost abstractions ### Frontend - **Code Splitting**: Next.js automatic code splitting - **Static Generation**: Pre-rendered pages where possible - **Optimized Images**: Next.js image optimization - **Bundle Analysis**: Webpack bundle analysis ## Security ### Backend Security - **Input Validation**: Domain-level validation - **Error Handling**: Secure error messages - **CORS**: Configurable CORS policies - **SQL Injection**: SQLx prevents SQL injection ### Frontend Security - **Type Safety**: TypeScript prevents type-related errors - **Input Validation**: Client-side validation with Zod - **XSS Prevention**: React automatic escaping - **CSRF Protection**: Built-in Next.js protection ## Future Enhancements ### Planned Features - **Authentication**: User authentication and authorization - **Role-Based Access Control**: User roles and permissions - **Product Categories**: Product categorization system - **Inventory Tracking**: Stock management - **Audit Logging**: Operation logging and history - **API Documentation**: OpenAPI/Swagger documentation - **Real-time Updates**: WebSocket support - **File Uploads**: Product image uploads - **Search and Filtering**: Advanced data filtering - **Pagination**: Large dataset handling ### Technical Improvements - **Caching**: Redis integration for caching - **Monitoring**: Application monitoring and metrics - **Logging**: Structured logging with correlation IDs - **Health Checks**: Application health endpoints - **Rate Limiting**: API rate limiting - **Compression**: Response compression - **CDN**: Static asset delivery optimization ## Contributing ### Development Guidelines - **Code Style**: Follow Rust and TypeScript conventions - **Testing**: Maintain high test coverage - **Documentation**: Keep documentation up to date - **Architecture**: Follow clean architecture principles - **Error Handling**: Comprehensive error handling - **Performance**: Consider performance implications ### Code Review Process - **Pull Requests**: All changes via pull requests - **Code Review**: Mandatory code review - **Testing**: Automated testing on all changes - **Documentation**: Update documentation as needed ## License This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License - see the [LICENSE.md](LICENSE.md) file for details. For more information about the license and compliance requirements, see [LICENSE_NOTICE.md](LICENSE_NOTICE.md).