devteam/sharenet
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sharenet/PROJECT_INDEX.md

18 KiB
Raw Blame History

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<T>: Generic repository trait for CRUD operations

Error Handling:

  • DomainError: Domain-specific error types (NotFound, InvalidInput, Internal)

Application Layer (backend/crates/application/)

Services:

  • Service<T, R>: Generic service implementation
  • UseCase<T>: Use case trait for business operations
  • Repository<T>: 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 <name> --email <email>
    • user get --id <id>
    • user list
    • user update --id <id> [--username <name>] [--email <email>]
    • user delete --id <id>
    • product create --name <name> --description <desc>
    • product get --id <id>
    • product list
    • product update --id <id> [--name <name>] [--description <desc>]
    • product delete --id <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

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

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 file for details.

For more information about the license and compliance requirements, see LICENSE_NOTICE.md.