TicTask is built to unify ticketing and task management through a modern, modular codebase. It aims to deliver a fast, scalable, and intuitive platform that reflects true software engineering principles.
Lightweight and modular architecture — easy to extend and maintain
Developer-friendly setup with Docker-first philosophy
Strict adherence to REST and OpenAPI standards
Secure-by-default authentication and role-based access
Seamless CI/CD with automated testing and staged rollouts
Deliver a robust, intuitive system that scales with teams — not against them.
TicTask follows a service-oriented architecture (SOA) built on Node.js + TypeScript, with React on the frontend and PostgreSQL as the main datastore.
Frontend — Next.js + React + MUI + Zustand/ Redux (state management)
Backend — Express.js/ Fastify services organized by domain
Database — PostgreSQL with Prisma ORM and schema migrations
Caching — Redis (for sessions, queues, and notifications)
Deployment — Dockerized microservices orchestrated via Docker Compose (dev) or Kubernetes (prod)
CI/CD — GitHub Actions for lint/test/build/deploy pipelines
Keep each service independently deployable and testable.
The repository uses a flat modular layout for clarity and maintainability.
Folder structure
├── / # root
├── backend/ # Backend service (Express/ Nodejs)
| ├── prisma/ # Database schema & migrations
| ├── src/
| | ├── controllers/ # API controllers
| | ├── lib/ # Shared helpers, templates and server utils
| | ├── middlewares/ # Middlewares
| | ├── routes/ # API routes
| | ├── validators/ # Validation schemas
| | ├── index.ts # Server entry point
| ├── Dockerfile
| ├── tsconfig.json
|
├── frontend/ # Frontend app (React/ Nextjs)
|
├── types/ # Shared types and interfaces
├── scripts/ # Dev scripts (seed, reset, lint)
└── docs/ # Public + developer documentationNode.js v20+
Next.js 15+
TypeScript 5.x
Prisma ORM
PostgreSQL 15+
Redis 7.x
Docker + Compose v2
GitHub Actions for CI/CD
Jest + Playwright for testing
TicTask favors stable LTS versions to ensure reproducible builds.
All environment variables are validated at runtime using Zod. Secrets are loaded from `.env` or a managed secret provider (e.g., Doppler, Vault, or AWS SSM).
.env.example
DATABASE_URL="postgresql://user:pass@localhost:5432/tictask"
REDIS_URL="redis://localhost:6379"
JWT_SECRET="your-secret-key"
NODE_ENV="development"Never commit .env files. Use .env.example for defaults and onboarding.
The schema follows a normalized relational model to ensure data consistency and fast lookups.
Users ↔ Workspaces ↔ Tickets (many-to-many relationships)
Tasks linked to tickets and subtasks
AuditLogs for key user and system actions
Notifications and Comments stored in separate tables with references
Migration command
npx prisma migrate dev --name init_schema
Each migration should be peer-reviewed and run in staging before production.
All endpoints follow REST conventions with predictable naming and pagination support.
Service endpoints
GET /api/tickets # List all tickets
POST /api/tickets # Create a new ticket
PATCH /api/tickets/:id # Update a ticket
DELETE /api/tickets/:id # Delete a ticket
GET /api/users/:id # Get user profile
POST /api/auth/login # Authenticate and issue tokenUse OpenAPI specs to document all public endpoints. Each service exports its own Swagger JSON.
Auth model: short-lived JWT access tokens with rotating, HttpOnly refresh tokens stored securely in the DB.
Auth endpoints
POST /auth/join # Register and verify email
POST /auth/login # Authenticate user credentials
POST /auth/refresh # Refresh access token
POST /auth/logout # Revoke refresh token
POST /auth/request-password-reset
POST /auth/reset-passwordPassword hashing: bcrypt (cost=12) or Argon2id
Tokens signed with HS256, expiresIn: 15m (access) / 7d (refresh)
CSRF-safe cookie settings with SameSite=Lax
Rate limiting on login, reset-password, and join routes
Audit log all login + refresh token events
Frontend built with Next.js (App Router) and MUI, emphasizing modular and accessible design.
Type Annotations - reusable types and interfaces
Atomic design principles — components organized by function
Reusable MUI wrappers for consistent branding
State management via Zustand and Redux Toolkit
Server actions for mutations (Next 15+)
Emotion caches, framer motions and hookform resolvers
Lazy loading for large modules and code-splitting per route
All shared components should live in packages/ui and be tree-shakeable.
Testing ensures stability across deployments and feature updates.
Unit tests — Jest for backend logic & utilities
Integration tests — Supertest for API endpoints
E2E tests — Playwright for full workflows (auth, tickets, tasks)
CI pipelines fail fast on any regression
Minimum coverage: 80% (critical modules must be 100%)
Run tests locally before commits using `npm run test:watch`.
GitHub Actions handles linting, testing, building, and deploying. Docker images are versioned and pushed to GHCR.
Main pipeline
on:
push:
branches: [main]
jobs:
build-test-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test
- run: docker build -t ghcr.io/tictask/app:latest .
- run: docker push ghcr.io/tictask/app:latestAlways test migrations and seed scripts on staging before deployment.
Operational best practices for maintaining uptime and recovery during incidents.
Restart containers: `docker compose restart api`
Rebuild cache: `docker exec api npm run cache:clear`
Run migrations manually: `npx prisma migrate deploy`
Inspect error logs: `docker logs api --tail=100`
Check DB health: `SELECT * FROM pg_stat_activity;`
If DB corruption or downtime occurs, restore from the latest automated backup snapshot stored in S3.
Clone repo: `git clone git@github.com:tictask/app.git`
Run `docker compose up -d`
Copy `.env.example` → `.env` and configure DB credentials
Run migrations: `npm run migrate` and `npm run seed`
Create test user and verify login via `/auth/login`
Use `npm run dev:web` and `npm run dev:api` for faster concurrent debugging.
© 2025 TicTask. All rights reserved.