bloboss · bloboss · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026
diff --git a/README.md b/README.md
@@ -1,224 +1,151 @@
-# Forgejo Classroom
+# Class Forge
 
-An educational assignment management system that integrates with Forgejo to provide GitHub Classroom-like functionality for self-hosted Git platforms.
+An educational assignment management system that integrates with self-hosted
+Git platforms (Forgejo and GitLab) to provide GitHub Classroom-like
+functionality.
 
-## Project Status
+## Features
 
-🚧 **This project is in early development** - Most functionality is not yet implemented. This repository contains the initial project structure and API framework.
-
-## Features (Planned)
-
-- **Classroom Management**: Create and manage coding classrooms
-- **Assignment Distribution**: Create assignments from template repositories
-- **Student Management**: Manage student rosters and account linking
-- **Team Support**: Support for both individual and team assignments
-- **Submission Tracking**: Automatic tracking of student submissions
-- **Deadline Enforcement**: Automatic deadline management with git tags
-- **CLI & API**: Complete CLI tool and REST API
+- **Classroom Management** - Create and manage coding classrooms tied to platform organizations/groups
+- **Assignment Distribution** - Create assignments from template repositories with automatic repo provisioning
+- **Student Management** - Manage student rosters and link to platform accounts
+- **Team Support** - Individual and team-based assignments with size limits
+- **Submission Tracking** - Automatic tracking when students accept assignments
+- **Deadline Enforcement** - Configurable deadlines per assignment
+- **Multi-Platform** - Supports both Forgejo and GitLab backends through a unified platform abstraction
+- **REST API** - Complete REST API for all operations
 
 ## Architecture
 
-This project follows a clean architecture with clear separation of concerns:
+Class Forge follows a layered architecture with clear separation of concerns:
+
+```
+API Handlers  ->  Service Layer  ->  Repository Layer  ->  PostgreSQL
+                       |
+                  Platform Provider (Forgejo / GitLab)
+```
 
-- **CLI Application** (`cmd/fgc/`) - Command-line interface for all operations
-- **API Server** (`cmd/fgc-server/`) - REST API for web integrations
-- **Service Layer** (`internal/service/`) - Business logic
-- **Repository Layer** (`internal/repository/`) - Data access
+- **API Server** (`cmd/fgc-server/`) - REST API with Gin framework
+- **CLI Tool** (`cmd/fgc/`) - Command-line interface
+- **Service Layer** (`internal/service/`) - Business logic and validation
+- **Repository Layer** (`internal/repository/`) - Data access with raw SQL
+- **Platform Abstraction** (`internal/platform/`) - Provider interface for Git platforms
 - **Models** (`internal/model/`) - Domain objects
-- **Forgejo Integration** (`internal/forgejo/`) - Forgejo API client
 
 ## Requirements
 
 - Go 1.21+
 - PostgreSQL 14+
-- Redis 7+
-- Docker & Docker Compose (for development)
-- Forgejo instance with API access
+- A Forgejo or GitLab instance with API access
 
 ## Quick Start
 
-### 1. Clone and Setup
+### 1. Build
 
 ```bash
-git clone <repository-url>
-cd forgejo-classroom
-
-# Copy configuration examples
-cp config.yaml.example config.yaml
-cp .env.example .env
-
-# Edit configuration files with your settings
+git clone https://code.forgejo.org/forgejo/classroom.git
+cd classroom
+make build
 ```
 
-### 2. Development Environment
+### 2. Configure
 
-```bash
-# Install dependencies
-make deps
+Create `config.yaml`:
 
-# Start development services (PostgreSQL + Redis)
-make docker-dev-up
+```yaml
+server:
+  port: 8080
+  mode: release
 
-# Build the applications
-make build
+platform:
+  type: forgejo    # or "gitlab"
 
-# Run tests
-make test
+forgejo:
+  base_url: https://your-forgejo.example.com
+  token: your-api-token
+
+database:
+  host: localhost
+  port: 5432
+  user: classforge
+  password: secret
+  name: classforge
+  ssl_mode: disable
 ```
 
-### 3. CLI Usage
+Or use environment variables with the `FGC_` prefix (e.g., `FGC_PLATFORM_TYPE=forgejo`).
 
-```bash
-# Build and test CLI
-make build-cli
+### 3. Run
 
-# Show help
-./bin/fgc --help
+```bash
+# Set up PostgreSQL database
+createdb classforge
 
-# Example commands (not yet implemented):
-./bin/fgc classroom create "CS 101" --org="university-cs"
-./bin/fgc assignment create "Homework 1" --classroom="cs-101" --template="https://your-forgejo.com/templates/hw1"
+# Start the server (migrations run automatically)
+./bin/fgc-server
 ```
 
-### 4. API Server
+### 4. Verify
 
 ```bash
-# Build and run API server
-make build-server
-./bin/fgc-server
-
-# Or with Docker
-make docker-build
-docker-compose up
+curl http://localhost:8080/healthz
+# {"status":"ok"}
 ```
 
+See the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - Installation, configuration, first classroom
+- [Configuration Reference](docs/configuration.md) - All config options and environment variables
+- [API Reference](docs/api-reference.md) - Complete REST API documentation
+- [Technical Design](design.md) - Architecture, schemas, and implementation strategy
+
 ## Development
 
 ### Project Structure
 
 ```
-forgejo-classroom/
-├── cmd/                    # Application entry points
-│   ├── fgc/               # CLI application
-│   └── fgc-server/        # API server
-├── internal/              # Private application code
-│   ├── api/               # API handlers and routing
-│   ├── service/           # Business logic
-│   ├── repository/        # Data access layer
-│   ├── model/             # Domain models
-│   ├── forgejo/           # Forgejo integration
-│   ├── cache/             # Caching layer
-│   ├── config/            # Configuration
-│   └── util/              # Utilities
-├── pkg/                   # Public libraries
-├── migrations/            # Database migrations
-├── test/                  # Integration tests
-└── docs/                  # Documentation
+class-forge/
+  cmd/
+    fgc/               CLI application
+    fgc-server/        API server
+  internal/
+    api/               HTTP handlers and routing
+    config/            Configuration loading
+    database/          Database connection and migrations
+    model/             Domain models
+    platform/          Git platform abstraction
+      forgejo/         Forgejo provider
+      gitlab/          GitLab provider
+    repository/        Data access layer (SQL)
+    service/           Business logic
+    util/              Shared utilities
+  migrations/          PostgreSQL migration files
+  docs/                User documentation
 ```
 
-### Development Workflow
-
-This project uses **Jujutsu (jj)** for version control. See `CLAUDE.md` for complete development guidelines.
+### Running Tests
 
 ```bash
-# Create new change
-jj new -m "Add feature description"
-
-# Run tests before committing
+# All unit tests
 make test
 
-# Describe your change
-jj describe -m "Detailed commit message"
+# Specific package
+go test ./internal/service/... -v
 
-# Push to remote
-jj git push
+# With coverage
+go test ./... -cover
 ```
 
-### Available Make Targets
+### Make Targets
 
-- `make build` - Build CLI and server
-- `make test` - Run all tests
-- `make test-integration` - Run integration tests
+- `make build` - Build CLI and server binaries
+- `make test` - Run unit tests
+- `make test-integration` - Run integration tests (requires Docker)
 - `make lint` - Run linters
-- `make docker-test-up` - Start test environment
-- `make dev-setup` - Set up development environment
-- `make clean` - Clean build artifacts
-
-## Configuration
-
-### Environment Variables
-
-Key environment variables (see `.env.example`):
-
-- `FGC_FORGEJO_BASE_URL` - Your Forgejo instance URL
-- `FGC_FORGEJO_TOKEN` - Forgejo API token
-- `FGC_DATABASE_*` - Database connection settings
-- `FGC_REDIS_*` - Redis connection settings
-
-### Configuration File
-
-See `config.yaml.example` for full configuration options.
-
-## API Documentation
-
-API documentation is available at `/api/v1` when running the server. The complete OpenAPI specification is documented in `design.md`.
-
-## Testing
-
-```bash
-# Unit tests
-make test-unit
-
-# Integration tests (requires Docker)
-make test-integration
-
-# All tests
-make test
-
-# Coverage report
-make coverage
-```
-
-## Contributing
-
-Please read `CONTRIBUTING.md` and `CLAUDE.md` for development guidelines.
-
-1. Understand the architecture in `design.md`
-2. Follow the development workflow in `CLAUDE.md`
-3. Write tests for new functionality
-4. Ensure all tests pass before submitting changes
+- `make clean` - Remove build artifacts
 
 ## License
 
 [License TBD]
-
-## Roadmap
-
-See `design.md` for detailed implementation phases and roadmap.
-
-### Phase 1: Core MVP (In Progress)
-- ✅ Project structure and build system
-- ✅ CLI framework
-- ✅ API framework
-- 🔄 Database layer
-- 🔄 Forgejo integration
-- ⏳ Basic classroom management
-- ⏳ Assignment creation
-
-### Phase 2: Assignment Distribution
-- ⏳ Template repository handling
-- ⏳ Student repository creation
-- ⏳ Assignment acceptance flow
-
-### Phase 3: Advanced Features
-- ⏳ Team support
-- ⏳ Deadline enforcement
-- ⏳ Submission tracking
-- ⏳ Statistics and reporting
-
-## Support
-
-For questions and support:
-- Check the documentation in `docs/`
-- Review the technical design in `design.md`
-- Create an issue for bugs or feature requests