jean/compare_functional_go_vs_dart
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme overhaus

Browse Source
This commit is contained in:
Jean Jacques Avril 2025-01-04 19:13:03 +00:00
parent f25815e617
commit 9a6c66adfc
No known key found for this signature in database
1 changed files with 138 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

271
README.md
View File

@ -1,65 +1,92 @@
# Time Tracking and Management System # ⏰ ActaTempus - Time Tracking and Management System
## Overview ## 🌟 Overview
The Time Tracking and Management System is a comprehensive web application **ActaTempus** is a modern, comprehensive web application designed to efficiently manage and track work hours. It features:
designed to manage and track work hours efficiently. The system showcases a - A **backend** developed in both Go and Dart, following **functional programming principles**.
backend developed in both Go and Dart with functional programming principles, - An interactive **React frontend** for an intuitive user experience.
and a React frontend to provide an interactive user experience.
## Features (longterm Goal) ---
- User management: Registration, login, profile updates. ## 🚀 Features (Long-Term Goals)
- Time tracking: Start/stop time tracking, manual entry, break management.
- Project management: Create and manage projects.
- Reporting: Generate daily/weekly reports and export as PDF/CSV.
- Real-time updates using WebSockets.
- Role-based access control (RBAC) with a permission system.
## Architecture ✅ **User Management**: Registration, login, and profile updates
✅ **Time Tracking**: Start/stop tracking, manual entries, and break management
✅ **Project Management**: Create and manage projects
✅ **Reporting**: Generate daily/weekly reports and export as PDF/CSV
✅ **Role-Based Access Control (RBAC)**: Fine-grained permission system
The project follows Domain-Driven Design (DDD) and Clean Architecture principles ---
to ensure a modular, maintainable, and scalable codebase. The system is
structured into well-defined layers with separation of concerns.
The backend logic is divided in four primary layers:
1. Domain-Layer: This layer contains only interfaces and definitions. Objects within can be regarded as contracts.
2. Infrastructure-Layer: This layer contains implementations that rely on external sourcs. (e.g. database, configuration files)
3. Application-Layer: All businesslogic is implemented within the application layer. This Layer defines how the applogic behaves and how the server responds.
4. Interface-Layer: Analogous to the Infrastructure-Layer, this Layer defines the external interface of the application.
![alt text](docs/media/architecture.png) ## 🏗️ Architecture
### Technology Stack This system follows **Domain-Driven Design (DDD)** and **Clean Architecture** principles to ensure a modular, maintainable, and scalable codebase.
It is structured into **four primary layers**:
- **Frontend**: React, Axios/Fetch API, WebSockets, Styled Components. 1️⃣ **Domain Layer**:
- **Backend (Go)**: - Contains contracts and interface definitions.
- GORM for ORM, `go-redis` for caching.
- `gorilla/websocket` and `gorilla/mux` for WebSocket and HTTP handling.
- **Backend (Dart)**:
- `drift` or `aqueduct` for ORM, `redis_client` for Redis integration.
- `shelf_web_socket` for WebSocket handling.
- **Databases**: PostgreSQL for primary data storage, Redis for caching and
real-time updates.
### Directory Structure 2️⃣ **Infrastructure Layer**:
- Implements external sources like databases and configurations.
- `backend-go/`: Go backend implementation. 3️⃣ **Application Layer**:
- `backend-dart/`: Dart backend implementation. - Implements business logic and server responses.
- `frontend-react/`: React frontend implementation.
- `docs/`: Documentation files, including LaTeX source for specifications and
design diagrams.
## Getting Started 4️⃣ **Interface Layer**:
- Defines the external-facing API.
![Architecture Diagram](docs/media/architecture.png)
---
## 🛠️ Technology Stack
### 🎨 Frontend:
- **React**: User Interface
- **Axios/Fetch API**: HTTP requests
- **WebSockets**: Real-time updates
- **Styled Components**: CSS-in-JS
### ⚙️ Backend:
#### Go:
- **GORM**: ORM for PostgreSQL
- **go-redis**: Redis integration
- **gorilla/websocket** & **mux**: WebSocket & HTTP routing
#### Dart:
- **drift/aqueduct**: ORM for database access
- **redis_client**: Redis integration
- **shelf_web_socket**: WebSocket handling
### 📦 Databases:
- **PostgreSQL**: Main data storage
- **Redis**: Caching and real-time updates
---
## 📁 Directory Structure
```
backend-go/ # Go backend implementation
backend-dart/ # Dart backend implementation
frontend-react/ # React frontend
docs/ # Documentation and design diagrams
```
---
## 📖 Getting Started
### Prerequisites ### Prerequisites
All prerequistes are already bundled with the devcontainer
- Node.js (for the React frontend) 💡 All dependencies are pre-configured in the **devcontainer**. If you're setting up manually, ensure you have:
- Go (for the Go backend) - [Docker](https://www.docker.com/)
- Dart (for the Dart backend) - Node.js (Frontend)
- PostgreSQL and Redis servers - Go (Go backend)
- Dart (Dart backend)
- PostgreSQL and Redis
### Installation ### 🔧 Installation
1. **Clone the repository**: 1. **Clone the repository**:
```bash ```bash
@ -67,135 +94,111 @@ All prerequistes are already bundled with the devcontainer
cd ws24-kp-avril cd ws24-kp-avril
``` ```
#### Requirements 2. **Use the devcontainer**:
Ensure the repository is on a **Unix-native file system** (e.g., WSL on Windows). Launch with Visual Studio Code:
```bash
code .
```
- Docker ---
- (WSL on Windows)
## 🖥️ Running the Software
# Run Software ### Frontend
You can start developing and hacking by starting the dev container. Besides that
you can also install the dev environment on your host system. Make sure versions
do match.
IMPORTANT: Place the repository on a unix native file system before starting the devcontainer. Otherwise you will experience severe performance issues.
On Windows I recommend pulling the git repository on a wsl instance. (e.g. Ubuntu)
Then navigate inside the folder and run ```code .``` to launch visual studio code. Visual Studio code then asks you if the devcointainer should be launched.
## Frontend
```bash ```bash
cd frontend-react cd frontend-react
#deno install # devcontainer does this for you deno run dev # Starts UI on port 3000
deno run dev # starts web ui on port 3000
``` ```
## Go-Backend ### Backend (Go)
```bash ```bash
cd backend-go cd backend-go
go run cmd/actatempus/main.go # Backend on port 8080 go run cmd/actatempus/main.go # Starts on port 8080
``` ```
## Dart-Backend ### Backend (Dart)
```bash ```bash
cd backend-dart cd backend-dart
dart run bin/backend_dart.dart # Backend on port 8080 dart run bin/backend_dart.dart # Starts on port 8080
``` ```
## Database
To simplify things, we chose to use prisma as orm. This enables us to use the same database definition for go and dart. Therefore also error prone manually written sql queries can be avoided. ---
In order to deploy the database schema you need to run ## 🗄️ Database Management
We use **Prisma ORM** for consistent database schema management across both backends.
### Deploy the Schema
```bash ```bash
bunx prisma db push bunx prisma db push
``` ```
The prisma cli can be initialized with the following command: ### Prisma Studio (UI)
```bash
bunx prisma
```
More: https://www.prisma.io/docs/orm/tools/prisma-cli
### Bun Studio
After deployment, data can be accessed via a webui:
```bash ```bash
bunx prisma studio bunx prisma studio
``` ```
### Codegen ### Code Generation
Inside the corresponding backend run: ```bunx prisma generate```
# Known Issues ```bash
bunx prisma generate
```
## Hydration issue caused by browser extensions ---
Some browserextensions inject js code. This leads to a mismatch between the ssr ## 🔧 Known Issues
and the client rendered version. In case of grammerly, you can see that some
attribute was injected in the dom `data-lt-installed="true"`
![alt text](docs/media/image.png)
### 🐛 Browser Extensions Cause Hydration Issues
## Roadmap Certain extensions (e.g., Grammarly) inject DOM attributes that cause SSR mismatches:
- Example: `<data-lt-installed="true">`
- Disable such extensions if issues occur.
1. Phase: Initialize ![Hydration Issue](docs/media/image.png)
- Definition with Spec
- Initialize Repository
2. Phase: Initial Setup
- Frontend with NextJS and Deno
- Backend
- Dart
- Go
- Dev-Container
3. Phase: Implement backends (first Iteration)
Goal: Implement working MVPs in GO and Dart to showoff functional programming in both languages
- Frontend foundation (basic setup, not connected to backend)
- Backend foundation
- Dart
- Go
- Domain
- Entities
- Repositories
- DataSources
- Application (Business Logic)
- Services (Endpoints)
- DTOs
- Authentication with JWT Token
- Simple Authorization
- Dart Testing
- Rpository Tests
- API Handler Tests
progress is currently here ---
3. Phase: Web UI (second Iteration) ## 🛣️ Roadmap
- Introduce Permission System
- Reporting for TimeEntries (with MapReduce...)
- Frontend
- Timetracker
- Manage Projects
- Manage TimeEntries
- Manage Tasks
- View Reports
Ideas for Advanced Features and further Iterations ### Phase 1: **Initialize**
- Exports (Excel, PDF) - ✅ Define specifications
- Maybe Billing - ✅ Initialize repository
- Multitennant
### Phase 2: **Setup**
- ✅ Frontend (NextJS, Deno)
- ✅ Backends (Dart & Go)
- ✅ Dev-container
## Resources ### Phase 3: **MVP Development**
- Build foundational backends in Go & Dart.
- Implement:
- ✅ Domain layer (Entities, Repositories)
- ✅ Business logic (Services, DTOs, JWT Authentication)
- ✅ Basic authorization
### Zen of Go ### Phase 4: **Web UI**
Best of do's and dont's - 🎨 Build frontend for:
https://the-zen-of-go.netlify.app/ - Timetracking
- Project management
- Reporting
### FP-Go Documentation ### Future Iterations
https://pkg.go.dev/github.com/IBM/fp-go - 📊 Report exports (Excel, PDF)
- 💳 Billing integration
- 🏢 Multi-tenant support
https://betterprogramming.pub/investigate-functional-programming-concepts-in-go-1dada09bc913 ---
## 🌐 Resources
### Go Programming
- [The Zen of Go](https://the-zen-of-go.netlify.app/)
### Functional Programming in Go
- [IBM FP-Go Documentation](https://pkg.go.dev/github.com/IBM/fp-go)
https://rlee.dev/practical-guide-to-fp-ts-part-1