https://github.com/idpass/idpass-data-collect
https://github.com/idpass/idpass-data-collect
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/idpass/idpass-data-collect
- Owner: idpass
- License: apache-2.0
- Created: 2025-06-10T19:20:58.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-02T06:05:36.000Z (4 months ago)
- Last Synced: 2026-03-02T10:52:30.302Z (4 months ago)
- Language: TypeScript
- Size: 4.36 MB
- Stars: 6
- Watchers: 0
- Forks: 3
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ID PASS DataCollect
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
> A robust offline-first data management system for household and beneficiary data with event sourcing and synchronization capabilities
## 🚀 Features
- **🔌 Offline-First Architecture** - Works seamlessly without internet using IndexedDB
- **🔄 Two-Level Synchronization** - Client ↔ Server ↔ External system sync
- **📝 Event Sourcing** - Complete audit trail of all data changes
- **🏢 Multi-Tenant Support** - Single backend serving multiple applications
- **🔐 JWT Authentication** - Secure API access with role-based permissions
- **🎯 TypeScript Throughout** - Type-safe development experience
- **📊 Conflict Resolution** - Automatic handling of data conflicts during sync
- **🔧 Extensible Architecture** - Custom event types and sync adapters
## 📦 Project Structure
This monorepo contains four main packages:
- **`packages/datacollect`** - Core library for offline data management
- **`packages/backend`** - Central sync server with PostgreSQL
- **`packages/admin`** - Vue.js admin interface for server management
- **`packages/mobile`** - Mobile application built with Vue.js and Capacitor
## 🚀 Quick Start
For setting up on Docker, see the [docker/README](docker/README.md)
### Prerequisites
- Node.js 20.x
- PostgreSQL 15+ (for backend)
- npm or yarn
### Installation
1. Clone the repository:
```bash
git clone https://github.com/idpass/idpass-data-collect.git
cd idpass-data-collect
```
2. Install dependencies and build:
```bash
# Install root dependencies
npm install
# Build datacollect library
cd packages/datacollect
npm install
npm run build
# Install backend dependencies
cd ../backend
npm install
# Install admin dependencies
cd ../admin
npm install
```
3. Set up environment variables:
```bash
cd ../..
cp .env.example .env
# Edit .env with your configuration
```
4. Start the development servers:
```bash
# Terminal 1: Backend server
cd packages/backend
npm run dev
# Terminal 2: Admin interface
cd packages/admin
npm run dev
```
## 📖 Documentation
- [Getting Started Guide](./website/docs/index.md)
- [Architecture Overview](./website/docs/architecture/index.md)
- [API Reference](./website/docs/api/datacollect/README.md)
- [Deployment Guide](./website/docs/deployment/docker-deployment.md)
- [Examples](examples/)
- [Glossary](./website/docs/glossary.md)
## 💻 Basic Usage
```typescript
import { EntityDataManager } from "idpass-data-collect";
// Initialize the data manager
const manager = new EntityDataManager(/* ... */);
// Create a household group
const household = await manager.submitForm({
type: "create-group",
data: { name: "Smith Family" },
// ... other fields
});
// Add members to household
const updated = await manager.submitForm({
type: "add-member",
entityGuid: household.guid,
data: {
members: [{ name: "John Smith", dateOfBirth: "1980-01-15" }],
},
// ... other fields
});
```
See [examples/basic-usage](./website/docs/examples/basic-usage/) for a complete example.
## 🏗️ Architecture
```mermaid
graph LR
A1[App 1 - DataCollect]<--> B[Backend Server]
A2[App 2 - DataCollect] <--> B
A3[App 3 - DataCollect] <--> B
B <--> C[External Systems]
B <--> D[(PostgreSQL)]
```
The system uses event sourcing with CQRS pattern:
- **Events** represent immutable changes to entities
- **Entities** represent current state (Groups and Individuals)
- **Sync** handles bidirectional data synchronization
- **Storage Adapters** abstract database operations
## 🧪 Testing
```bash
# Run all tests
npm test
# Run tests for specific package
cd packages/datacollect && npm test
cd packages/backend && npm test
cd packages/admin && npm run test:unit
# Run with coverage
npm test -- --coverage
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
- Code of Conduct
- Development setup
- Submitting pull requests
- Coding standards
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [GitHub Repository](https://github.com/idpass/idpass-data-collect)
- [Issue Tracker](https://github.com/idpass/idpass-data-collect/issues)
- [Website](https://acn.fr)
## 👥 Authors
Developed and maintained by [Association pour la Coopération Numérique](https://acn.fr)
---
For questions or support, please [open an issue](.github/ISSUE_TEMPLATE) or contact the maintainers.