This is an automated email from the ASF dual-hosted git repository.
dimas pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 9648582fd docs(README): Create Polaris-Core README (#2585)
9648582fd is described below
commit 9648582fd30494467e09250d79b0f6a1bc4383a3
Author: Adam Christian
<105929021+adam-christian-softw...@users.noreply.github.com>
AuthorDate: Wed Sep 17 12:43:29 2025 -0700
docs(README): Create Polaris-Core README (#2585)
* docs(README): Create Polaris-Core README
---
README.md | 8 +++++---
polaris-core/README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 56 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 633fe36a7..60076011b 100644
--- a/README.md
+++ b/README.md
@@ -42,11 +42,11 @@ Click [here](https://polaris.apache.org/in-dev/unreleased/)
for a quick overview
## Quickstart
Click
[here](https://polaris.apache.org/in-dev/unreleased/getting-started/install-dependencies/)
for the quickstart experience, which will help you set up a Polaris instance
locally or on any supported cloud provider.
-## Building and Running
+## Project Structure
Apache Polaris is organized into the following modules:
-- `polaris-core` - The main Polaris entity definitions and core business logic
+- [`polaris-core`](./polaris-core/README.md) - The main Polaris entity
definitions and core business logic
- API modules (implementing the Iceberg REST API and Polaris management API):
- `polaris-api-management-model` - The Polaris management model
- `polaris-api-management-service` - The Polaris management service
@@ -59,7 +59,9 @@ Apache Polaris is organized into the following modules:
- Persistence modules:
- `polaris-eclipselink` - The Eclipselink implementation of the
MetaStoreManager interface
- `polaris-relational-jdbc` - The JDBC implementation of BasePersistence to
be used via AtomicMetaStoreManager
-
+
+## Building and Running
+
Apache Polaris is built using Gradle with Java 21+ and Docker 27+.
- `./gradlew build` - To build and run tests. Make sure Docker is running, as
the integration tests depend on it.
diff --git a/polaris-core/README.md b/polaris-core/README.md
new file mode 100644
index 000000000..a6d32c324
--- /dev/null
+++ b/polaris-core/README.md
@@ -0,0 +1,51 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Polaris-Core Module
+
+The `polaris-core` module contains the fundamental entity definitions, core
business logic, and foundational interfaces that power Apache Polaris.
+
+## Overview
+
+`polaris-core` handles:
+- Entity Management
+- Security & Access Control
+- Common Persistence Logic
+- Object Storage Integration
+
+## Key Components
+
+### Entity Management
+Polaris has several different entities defined in `PolarisEntityType`. You can
find their definitions in the package `org.apache.polaris.core.entity`.
+
+### Security & Access Control
+Polaris uses a role-based access control (RBAC) model. `PolarisPrivilege`
defines the available privileges. The RBAC model is implemented in
`PolarisAuthorizer`. For more information on authorization, see the package
`org.apache.polaris.core.auth`.
+
+### Common Persistence Logic
+To store entities, Polaris provides a persistence layer built upon the
`BasePersistence` interface. Common persistence logic is handled in the
`org.apache.polaris.core.persistence` package. Implementations are found within
[the persistence folder](../persistence).
+
+### Object Storage Integration
+Polaris supports multiple object storage providers.
`PolarisStorageIntegration` provides an interface for accessing and managing
data in object stores. For more information, see the package
`org.apache.polaris.core.storage`.
+
+## Usage
+
+The `polaris-core` module is primarily consumed by:
+- **API Services** - Management and catalog REST services
+- **Runtime Components** - Server and admin tools
+- **Persistence Implementations** - Eclipselink, JDBC, etc.
