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

415 lines
No EOL
18 KiB
Markdown
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
```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).
Reference in a new issue View git blame Copy permalink