An enterprise-grade, multi-tenant agency management platform unifying client CRM, project planning, Kanban task tracking, live stopwatch time tracking, and automated PDF invoice generation with strict database schema-level isolation.
Explore Repositories • Architecture • Key Features • Tech Stack • Quick Start • Security & Multi-Tenancy
Agency OS streamlines everyday agency operations into a singular, cohesive workspace. It eliminates fragmented toolchains by combining customer relationship management, project budgeting, team timesheets, live stopwatch synchronization, and automated branded invoice generation under a high-security, multi-tenant architecture.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Client CRM │ ───► │ Projects & Tasks│ ───► │ Live Tracking │
│ Prospect/Active│ │ Kanban & Budget│ │Stopwatch & Logs │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Workspace Sync │ ◄─── │ Role-Based RBAC│ ◄─── │ PDF Invoicing │
│ Schema Isolation│ │Keycloak + OIDC │ │Automated Billing│
└─────────────────┘ └─────────────────┘ └─────────────────┘
| Repository | Description | Tech Stack | Status |
|---|---|---|---|
| front-end | Modern SPA client with pure standalone architecture, reactive Signals, dark/light UI, and interactive demo personas. | Angular 22, TypeScript 6, Tailwind CSS v4, Signals, Vitest, STOMP | |
| back-end | Enterprise REST API and real-time WebSocket server with Flyway schema-per-tenant multi-tenancy and PDF generation. | Java 21, Spring Boot 4.1, PostgreSQL, Keycloak, Apache PDFBox, JaCoCo |
graph TB
subgraph ClientLayer ["Client Presentation Layer"]
SPA["Angular 22 SPA<br/>(Signals • Tailwind CSS v4 • Vitest)"]
end
subgraph AuthLayer ["Identity & Access Management"]
KC["Keycloak IdP<br/>(OAuth2 / OIDC • PKCE • JWT)"]
end
subgraph ApiGateway ["Spring Boot 4.1 Backend Engine"]
SEC["Spring Security Filter Chain<br/>(Bearer JWT + JIT User Sync)"]
TSF["Tenant Security Interceptor<br/>(Validates X-Tenant-ID)"]
REST["REST API Controllers<br/>(/api/v1/*)"]
WS["WebSocket / STOMP Broker<br/>(/ws-timer, /topic)"]
PDF["Apache PDFBox Engine<br/>(Branded PDF Invoices)"]
end
subgraph DatabaseLayer ["PostgreSQL 15+ (Schema-per-Tenant)"]
PUBLIC_DB[("public schema<br/>app_users, workspaces, memberships")]
TENANT_A[("tenant_acme_* schema<br/>clients, projects, tasks, times, invoices")]
TENANT_B[("tenant_globex_* schema<br/>clients, projects, tasks, times, invoices")]
end
SPA -->|OAuth2 / PKCE Login| KC
KC -->|JWT Access Token| SPA
SPA -->|REST Requests + Bearer Token + X-Tenant-ID| SEC
SPA <-->|Real-Time Timer Sync| WS
SEC --> TSF
TSF --> REST
REST --> WS
REST --> PDF
REST -->|Global Auth & Workspaces| PUBLIC_DB
REST -->|Dynamic Tenant Routing| TENANT_A
REST -->|Dynamic Tenant Routing| TENANT_B
- Complete data isolation with dedicated PostgreSQL schemas (
tenant_<slug>_<suffix>) provisioned automatically on workspace creation. - Tenant context dynamically resolved via the
X-Tenant-IDrequest header with strict authorization checks.
- Manage client lifecycles (
PROSPECT,ACTIVE,INACTIVE), billing contacts, and notes. - Plan fixed-budget projects, set hourly billing rates (
billingRate), track deliverable progress, and assign client portal access.
- Drag-and-drop status workflows (
TODO->IN_PROGRESS->REVIEW->DONE). - Task assignees, priority bands (
LOWtoURGENT), due dates, and real-time budget burn calculations.
- Run browser-based stopwatches (start, pause, resume, stop) with sub-second accuracy.
- Real-time STOMP over SockJS broadcasting timer status updates across all connected teammates.
- 1-click aggregation of unbilled billable hours mapped against project hourly rates.
- Generates pixel-perfect, multi-page branded PDF invoices with itemized task breakdowns using Apache PDFBox.
- Built-in in-app PDF preview modal and payment tracking (
DRAFT,SENT,PAID,CANCELLED).
- Integrated Keycloak OpenID Connect / OAuth2 Resource Server validation.
- Role-Based Access Control (RBAC):
OWNER,ADMIN,MEMBER, andCLIENTpersonas with method-level@PreAuthorizesecurity.
| Domain | Technologies & Libraries |
|---|---|
| Front-End | Angular 22, TypeScript 6, Tailwind CSS v4, Angular Signals (signal, computed, effect, httpResource), @angular/router, RxJS |
| Back-End | Java 21 (Temurin), Spring Boot 4.1, Spring Data JPA, Hibernate, Spring Security, Spring WebSocket (STOMP), Flyway |
| Identity & Auth | Keycloak OIDC, OAuth2 Resource Server, JWT with PKCE, Spring Security SpEL Method Authorization |
| Database | PostgreSQL 15+ with Schema-per-Tenant architecture |
| Document Processing | Apache PDFBox 3.0 |
| Testing & Quality | Vitest, JaCoCo (≥80% line coverage), Spotless (Google Java Format), Checkstyle, SonarQube, ESLint, Prettier |
| DevOps & Packaging | Docker, Docker Compose, Jenkins CI/CD Pipeline |
- Java 21+ (Eclipse Temurin recommended)
- Node.js 20+ & npm 10+
- PostgreSQL 15+
- Keycloak 24+ (configured with
agency-osrealm) - Docker & Docker Compose (optional for containerized run)
Make sure PostgreSQL and Keycloak are up and running:
- PostgreSQL:
localhost:5432(database:agency_os) - Keycloak:
http://localhost:8080(realm:agency-os, client:agency-os-frontend&agency-os-backend)
# Clone the repository
git clone https://github.com/Agnecy-OS/back-end.git
cd back-end
# Copy and adjust environment variables
cp .env.example .env
# Run database migrations and start the server
./mvnw spring-boot:run- API Base URL:
http://localhost:8080/api/v1 - Swagger / OpenAPI Docs:
http://localhost:8080/swagger-ui.html - WebSocket Endpoint:
ws://localhost:8080/ws-timer
# Clone the repository
git clone https://github.com/Agnecy-OS/front-end.git
cd front-end
# Install dependencies
npm install
# Start the development server
npm start- Web Application:
http://localhost:4200 - Demo Showcase Personas:
http://localhost:4200/demo
HTTP Request Headers:
Authorization: Bearer <Keycloak-JWT-Token>
X-Tenant-ID: <Tenant-Schema-Identifier>
| Role | Workspace Access | Client CRM | Projects & Tasks | Timesheets | Invoices |
|---|---|---|---|---|---|
| OWNER | Full Control, Transfer, Delete | Read / Write / Delete | Read / Write / Delete | All Users | Full Control |
| ADMIN | Invite / Manage Members | Read / Write / Delete | Read / Write / Delete | All Users | Full Control |
| MEMBER | Read Members | Read-Only | Assigned Projects/Tasks | Self Only | Read-Only |
| CLIENT | Limited View | Read Own Profile | Read Scoped Projects | None | View / Download Own |
cd front-end
npm run test # Vitest unit tests
npm run lint # ESLint verification
npm run format:check # Prettier verificationcd back-end
./mvnw clean test # Unit & integration tests
./mvnw jacoco:report # Coverage report (≥80% gate)
./mvnw spotless:check checkstyle:check # Code style validationMaintained by Eyad Sharkawy.